INTERNET DRAFT
David Manning, Richard Bennett, John Boyer,
Sonja McLellan, Michael Mansell
July 1997
Expires: February 02, 1997
Universal Forms Description Language Specification
Version 3.2
<draft-gordon-ufdl-spec-00.txt>
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
1. INTRODUCTION 4
1.1 Introduction to the UFDL 4
1.2 UFDL Documentation 5
1.3 Requirement Levels for UFDL Elements 6
1.4 Implied Semantics for UFDL Viewers 6
1.5 Security Considerations 8
1.6 Responding to Errors in the Form Description 8
Universal Forms Description Language [page 1]
2. THE UNIVERSAL FORMS DESCRIPTION LANGUAGE 9
2.1 What is the UFDL? 9
2.2 Features of UFDL Forms 10
2.3 Description of a UFDL Form 12
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 17
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 24
2.4j References to Other Options 24
2.4k Dynamically Created Options 25
2.4l Operations 28
2.4m Arrays 30
2.4n Defining Tabbing and Paging 32
2.4o Including External Files 35
2.5 UFDL Language Elements 36
2.5a Identifiers 37
2.5b Custom Item Types and Custom Option Names 37
2.5c Reserved Words 37
2.5d Quoted Strings 37
2.5e Binary Data 38
2.5f Comments 38
2.6 Processing Forms 38
2.6a Include Statements 39
2.6b Expressions 39
3. UFDL GLOBAL AND PAGE SETTINGS 39
3.1 Global settings 40
3.2 Page settings 41
4. UFDL FORM ITEMS 42
4.1 action 43
4.2 box 45
4.3 button 45
4.4 cell 47
4.5 check 48
4.6 combobox 49
4.7 data 51
4.8 field 52
4.9 help 54
4.10 label 55
4.11 line 56
4.12 list 57
4.13 popup 59
Universal Forms Description Language [page 2]
4.14 radio 61
4.15 spacer 63
4.16 tablet 64
4.17 toolbar 66
4.18 <custom item> 67
5. UFDL FORM OPTIONS 68
5.1 active 71
5.2 bgcolor 72
5.3 bordercolor 73
5.4 borderwidth 73
5.5 coordinates 74
5.6 datagroup 75
5.7 delay 76
5.8 editstate 77
5.9 filename 78
5.10 fontcolor 78
5.11 fontinfo 79
5.12 format 80
5.13 group 86
5.14 help 87
5.15 image 87
5.16 itemlocation 88
5.17 justify 96
5.18 label 97
5.19 labelbgcolor 98
5.20 labelbordercolor 98
5.21 labelborderwidth 99
5.22 labelfontcolor 100
5.23 labelfontinfo 100
5.24 mimedata 101
5.25 mimetype 102
5.26 next 103
5.27 printsettings 104
5.28 saveformat 106
5.29 scrollhoriz 109
5.30 scrollvert 109
5.31 size 110
5.32 thickness 111
5.33 transmit 112
5.34 transmitformat 113
5.35 transmititems 117
5.36 transmitoptions 119
5.37 triggeritem 120
5.38 type 121
5.39 url 123
5.40 value 124
5.41 version 125
5.42 <custom option> 126
6 UFDL FORM VIEWER DIRECTIVE 127
6.1 #include 127
APPENDIX A: QUICK REFERENCE TABLES 128
A.1 Table of Items & Form & Page Characteristics 128
Universal Forms Description Language [page 3]
A.2 Table of Options 130
APPENDIX B: DEFAULT SIZES 136
APPENDIX C: GRAMMAR OF THE UFDL 138
C.1 Symbols 138
C.2 Production Rules 139
APPENDIX D: UFDL FOR C AND C++ PROGRAMMERS 141
D.1 Procedural vs. State Language 141
D.2 Globals and Functions (Pages) 141
D.3 References and Dereferencing 142
D.4 Arrays 143
D.5 Assignment 144
APPENDIX E: GLOSSARY 144
AUTHOR CONTACT INFORMATION 148
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.
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
Universal Forms Description Language [page 4]
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
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
Universal Forms Description Language [page 5]
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
- 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
Universal Forms Description Language [page 6]
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
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
Universal Forms Description Language [page 7]
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
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
Universal Forms Description Language [page 8]
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.
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:
- Can be passed whole from node to node in a distribution chain.
- Appear the same on any platform and under any screen resolution
and system font size.
- Let users work offline or online.
- Can perform logical operations.
- Give users editing and error checking tools.
- 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
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
Universal Forms Description Language [page 9]
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
developers and 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 D: UFDL for C and C++ Programmers. This appendix outlines
the 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.
Universal Forms Description Language [page 10]
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 behaviour. 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
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.
Automatic Actions
The UFDL supports automatic timed behaviour 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.
Universal Forms Description Language [page 11]
Logical Operations and Arithmetic Computations
The UFDL uses a set of options to describe a form object's
appearance and behaviour. 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 behaviour to occur at run-time.
Stand Alone Definitions
All aspects of a form's appearance, behaviour, 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. 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
Universal Forms Description Language [page 12]
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 behaviour, 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:
version = "3.2.0";
bgcolor = ["224", "224", "224"];
page_1 = new page
{
bgcolor = ["224", "224", "224"];
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 the 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.
In some senses, pages act like independent forms. They have their
own size, appearance, toolbars, and characteristics. As well,
relational positioning of the items on a page is based solely on
other items on the same page.
The following example shows a page containing a label and a button:
Universal Forms Description Language [page 13]
page_1 = new page
{
bgcolor = ["224", "224", "224"];
hello_label = new label
{
value = "Hello, world.";
fontcolor = ["0", "0", "255"];
}
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 the UFDL'.
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.
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 14]
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 '4. UFDL Form Items' 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.
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 Modified size overriding the
characteristics only 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.
Universal Forms Description Language [page 15]
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"];
transmit = "all";
}
For more information on the syntax rules of an item's description,
see '2.4 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
behaviour 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 = ["224", "224", "224"];
page_1 = new page
{
...
page_1 = new page
{
bgcolor = ["224", "224", "224"];
bar_box = new box
{
...
bar_box = new box
{
bgcolor = ["0", "0", "0"];
size = ["60", "5"];
}
...
Universal Forms Description Language [page 16]
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
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 behaviour
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:
<version definition statement>*
<option definitions for the form characteristics>
<page definition1>
...
<page definitionn>**
Universal Forms Description Language [page 17]
* mandatory statement. See '5.41 version' for the syntax of this
statement.
** there is no limit placed on the number of page definitions
in a form; however, every form must contain at least one page
definition.
For example:
version = "3.2.0";
bgcolor = ["224", "224", "224"];
fontinfo = ["Helvetica", "10", "plain"];
//This is page 1
page_1 = new page
{
<option definitions for the page settings>
<item definitions for items located on page 1>
}
//This is page 2
page_2 = new page
{
<option definitions for the page settings>
<item definitions for items located on page 2>
}
...
//This is page 10
page_10 = new page
{
<option definitions for the page settings>
<item definitions for items located on page 10>
}
Defining global settings for the form is optional. It has the effect
of setting characteristics that apply to the entire form. In the
previous example, version, bgcolor, and fontcolor are global
settings. These characteristics override the defaults defined by
the UFDL. Specific pages and items will override these global
settings if the same option has been defined differently for that
page or item.
2.4c Page Definition
The syntax of a page definition is as follows:
<page tag> = new page
{
<option definitions for the page characteristics>
<item definition1>
...
<item definitionn>
}
Notes:
i) The braces are mandatory.
Universal Forms Description Language [page 18]
ii) A page definition must begin on a new line.
iii) Item definitions are optional and there is no limit placed on the
number of item definitions in a page.
The page tag uniquely identifies a page instance. No two page tags
in a form can be the same. See section '2.5a Identifiers' for tag
naming conventions.
Defining page characteristics is optional. It has the effect of
setting options that are global to that page. These characteristics
override the defaults defined by the UFDL and any global options set
by the form characteristics. Specific items will override the page
settings if the same option has been defined differently for that
item.
In the following example, you can see a sample page definition. The
page tag is Page_one and the page contains a label and a button.
The page has a background color of grey (RGB VALUE of 224, 224, 224)
and each item on the page will have a font of Times 14.
Page_one = new page
{
bgcolor = ["224", "224", "224"];
fontinfo = ["Times", "14", "plain"];
button_label = new label
{
<option definitions for the label characteristics>
}
save_button = new button
{
<option definitions for the button characteristics>
}
}
2.4d Item Definition
The syntax of an item definition is as follows:
<item tag> = new <item type>
{
<option definition1>
...
<option definitionn>
}
Notes:
i) The braces are mandatory.
ii) An item definition must begin on a new line.
iii) Option definitions are optional.
iv) You cannot assign values to options in other item definitions.
The item tag uniquely identifies an item instance. No two item tags
on a page can be the same. See section '2.5a Identifiers' for tag
naming conventions.
Item type is a name that identifies the type of item. Examples of
Universal Forms Description Language [page 19]
item types are: button, label, field, line, and check. See the
section ' 4 UFDL Form Items' for a description of each item type.
There is a finite list of UFDL-defined options applicable to each
type of item. You can code as many or as few from the list as you
wish. There are default settings for most options (defined by
the UFDL). You may choose to use those defaults or to define your
own settings. Defining your own settings overrides the defaults.
You can also create your own item types. A UFDL parser will ignore
these custom item types, but you can use them to store information
specific to your application, and then refer to them in other item
descriptions in the form. For more information on how to refer to
options in the form, see 'Referring to Other Options' later in this
section.
In the following example, you can see a sample button definition.
The button has the following characteristics:
- The item tag is save_button.
- It will save the form to a file on the user's workstation.
- The button's label is Save Form.
- The background color is grey.
- The font used for the label is Helvetica 12.
save_button = new button
{
bgcolor = ["224", "224", "224"];
fontinfo = ["Helvetica", "12"];
type = "save";
value = "Save Form";
}
2.4e Item Size
Every external item has a characteristic shape. Many items also
contain data such as text and images. This is the basic item. For
example, the basic field is a rectangular space where users can
input text. Buttons are rectangular objects containing a
descriptive label.
Items may also contain the following elements:
- borders
- an external label
- scroll bars
Borders are lines outlining an item's shape. Their use is optional
and their thickness is variable.
External labels are part of an item's definition but they occupy
their own space. An example of an external label is the label you
define for a field. This label occupies space above the field
item.
Several types of items permit users to scroll the data the item
contains. Typically, scroll bars appear with these items. Examples
Universal Forms Description Language [page 20]
of items permitting scrolling are fields and lists.
Size Calculation
There are two sizes calculated for an item. They are:
- basic item size
- the item's bounding box
The basic item size is composed of the item's characteristic shape
and any imbedded data. The UFDL defines a set of default basic item
sizes. You can choose to use these defaults or you can define the
size using the size option. When deciding whether to define the size
and what size to specify, you will want to consider any data
imbedded in the item.
The bounding box is an unseen rectangular area surrounding each item
and including all elements of the item. The size of the bounding box
depends on the sizes of the various elements. The UFDL calculates
this size, taking into account the basic item size and the
existence and size of the various optional elements. For example,
if the item definition contains a borderwidth setting (meaning the
item has a border), then the bounding box size encompasses the basic
item and the space occupied by the border.
See 'Appendix B: Default Sizes' for the default item and
bounding box sizes.
Altering Size Dynamically
You can dynamically alter the bounding box size, and thus the basic
item size and the space available for the external label. The
itemlocation option contains various directives permitting you to
do this.
A bounding box has six edges: left, right, top, bottom, vertical
center, and horizontal center. You can align any of these edges with
the edge of another item's bounding box (called a reference item in
this context). Once you have aligned one edge, you can expand the
bounding box until the far edge aligns with another location. In
this manner, you override the bounding box length in that direction.
For example, you can align the left edge with the horizontal center
of one reference item. You can then expand the right edge until it
aligns with the right edge of the original reference item or a
second reference item. This pair of directives sets the bounding
box width.
2.4f Item Placement
The UFDL supports two different positioning schemes to place
external items on a page: relational positioning and absolute
positioning.
Relational positioning means an item's location depends on the
location and size of one or more other items on the page. This
Universal Forms Description Language [page 21]
feature is similar to the mechanism used for dynamic sizing.
Relational positioning uses the bounding boxes of the other items as
reference points. Items align relative to these bounding boxes. You
must define the location of the other items before you can use them
as reference points.
The item location option provides various directives you can use to
specify an item's location. For example, you might place an image
before a radio and expand its bottom edge to the bottom edge of the
radio button.
The only items whose placement is not affected by relational
positioning are the first item in the toolbar and the first item in
the body of the page. The first item assigned to the toolbar goes in
the top left corner of the toolbar. The first item not assigned to
the toolbar goes in the top left corner of the body.
Absolute positioning places an item in an absolute position on the
page, anchoring it to a particular coordinate. This coordinate is a
pair of pixel measurements defining the item's distance from the top
left corner of the page.
Absolute positioning also allows items to be offset from their
original position, in order to make layout with an absolute
positioning scheme more flexible. When offsetting an item, the form
developer first places the item on the page and then specifies how
far it should be offset from that position.
The absolute positioning scheme's advantage is that it makes
designing a drag-and-drop form designer easy. Absolute positioning
is not a good cross-platform solution, however, and in order to
ensure that forms appear consistent on all platforms, developers
should use either strictly the relational positioning scheme, or a
careful combination of relational and absolute positioning.
For more information, see 5.16 itemlocation option description
2.4g Toolbar Definition
A toolbar is a section that stretches across the top of a page in
which items can be placed for quick access. If a user scrolls down
on a page, the toolbar remains visible.
A user defines a toolbar using the toolbar item. Each page can have
one toolbar, and the toolbar will appear on only that page. Place
items in the toolbar by using the within modifier of the
itemlocation option.
The following example shows the definition of a toolbar with two
items: a label and a close button.
p1_toolbar = new toolbar
{
Universal Forms Description Language [page 22]
bgcolor = ["224", "224", "224"];
}
title_label = new label
{
value = "Student Registration Form";
fontinfo = ["Helvetica", "16", "bold"];
itemlocation = [["within", "p1_toolbar"]];
}
close_button = new button
{
type = "close";
value = "Close Form";
itemlocation = [["within", "p1_toolbar"], ["below", "title_label"],
["alignhorizc2c", "title_label"]];
}
2.4h Option Definition
An option definition is an assignment statement that assigns one
characteristic to an item, a page, or to the whole form. The
expression on the right hand side of the equal sign contains the
option's setting. The syntax of an option definition statement is
as follows:
<option identifier> = <expression>;
Note: The semicolon is mandatory and terminates the statement.
For example:
value = "Submit Form";
fontinfo = ["Helvetica", 16", "bold"];
url = global.global.db_address
Explanation of Syntax
Option identifier is a name that identifies the type of option.
It can be a UFDL-defined option or a user-defined option. Examples
of option identifier are: bgcolor, fontinfo, itemlocation, and size.
See section '5 UFDL Form Options' for a description of each option
and its possible values.
An expression specifies a value. An expression can be any of the
following:
- a literal
(for example, the right hand side of
value = "Submit Form"; )
- a reference to another option definition in the form
(for example, the right hand side of
url = global.global.db_address; )
- an operation
(for example, the right hand side of
value = total_field.value + "3400"; )
- an array specification
(for example, the right hand side of
fontinfo = ["Helvetica", "16", "bold"]; )
Universal Forms Description Language [page 23]
2.4i Literals
Specify a literal as a quoted string. This is true even for operands
of an operation. Examples of using literals are:
"V3.2.0" - yields "V3.2.0"
"1" + "2" - yields "3"
"UFDL\\" +. "form1" - yields "UFDL\\form1"
2.4j References to Other Options
In order to copy information from one place in the form to another,
or to make a decision based on the contents of items in the form, a
developer needs to refer to one or more other options in the form.
This is done using an option reference. The referenced option
definition can exist anywhere in the form definition, including
after the current statement.
For examples of option references, see the paragraphs following the
box below. An option reference has several possible formats:
1. for options in the current item definition use one of the
following:*
- <option reference>
- <option reference>-><option reference>
2. for options in another item definition use one of the following:*
- <item reference>.<option reference>
- <item reference>.<option reference>-><option reference>
3. for options in page characteristics use one of the following:
- global.<option reference>
- for characteristics on the current page
- <page tag>.global.<item reference>
- for characteristics on another page
4. for options in form characteristics use:
global.global.<option reference>
where <option reference> is one of:
- <option identifier>
- for the complete option setting (it can be a single
value or an array)
- <option identifier>[<array element>]
- for one element of an array**
and <item reference> is one of:
- <item tag>
- for items on the current page
- <page tag>.<item tag>
- for items on another page
and the indirect membership operator (->) indicates:
- a dynamic option reference
The phrase '-> <option reference>' can occur any number of
times on the right hand side of an option statement.
See '2.4m Array References' for information on
Universal Forms Description Language [page 24]
<array element>.
In order to refer to an option that varies depending on what the
user of a form enters, use a dynamic option reference. For example,
a form developer cannot know what cell a user will choose in a popup
menu. To refer to the value of whatever cell the user chooses, the
developer must use a dynamic option reference. For example:
popup_menu.value->value
A dynamic option reference (-> <option reference>) provides a
mechanism for determining the location of the option at run-time.
The references preceding the indirect membership operator must
resolve to an item reference or a reference to the form or page
characteristics.
Examples of option references are:
- an item on the current page:
list_one.value
This identifies the value option of the item whose item reference is
list_one.
- a form characteristic:
global.global.bgcolor
This identifies the bgcolor option specified at the top of the form,
as a form global characteristic.
- a dynamic option reference with one level of indirection:
my_choice.value->bgcolor
The my_choice.value setting becomes the item reference for the
bgcolor option. If, for example, my_choice.value contains "global",
then this reference is equivalent to global.bgcolor.
- a dynamic option reference with two levels of indirection:
my_choice.value->value->bgcolor
The my_choice.value setting becomes the item reference for the value
option. If, for example, my_choice.value contains "your_choice",
then my_choice.value->value is equivalent to your_choice.value.
If your_choice.value contains "page_two.global", then the complete
reference is equivalent to page_two.global.bgcolor.
2.4k Dynamically Created Options
The UFDL contains a set of special options that allow you to refer
to a page, item, or option without knowing the page tag and/or item
Universal Forms Description Language [page 25]
tag you would normally include in such a reference. For example, if
you wanted to refer to a button on the next page in your form,
normally you would need to know the page tag of the page that button
was on. Using the UFDL's special reference options, you could make
the reference without knowing the page tag. You would write the
reference this way:
pagenext->submit_button.url
To refer to pages or items in the form without knowing their tags,
you may use the following reference option names:
Option name Meaning
itemnext Next item in the page's description. The last
points to the first item oln the current page.
itemprevious Previous item in the page's description. The
first item points to the last item on the
current page.
pagenext Next page in the form description. The last
page points to the first page.
pageprevious Previous page in the form description. The
first page points to the last page.
itemfirst First item in the current page description.
itemlast Last item in the current page description.
pagefirst First page in the form description
pagelast Last page in the form description.
Creating references with reference options
To create references using the reference option names, follow the
normal rules for option references (see "References to Other
Options" earlier in this section). Note that because the reference
options exist at the option level, but are evaluated to pages or
items, you need to use the dereference symbol (->) when using them.
Examples
- The value of the next item on the current page:
itemnext->value
- The value of the first item on the next page:
global.pagenext->itemfirst->value
- The url setting of an item called submit_button on the
previous page:
global.pageprevious->submit_button.url
Universal Forms Description Language [page 26]
- The first item on the first page of the form:
global.global.pagefirst->itemfirst
Techical Note - How reference options are added to forms
Special reference options are dynamically added to the form when it
is parsed. For example, on every page, the parsing program inserts a
pagenext option into the page global settings. This pagenext option
contains the item tag of the next page in the form. It also inserts
a pageprevious, itemfirst, and itemlast option into the page global
settings. Each of these options contains the appropriate page tag or
item tag. Form developers cannot add these options to forms; only
programs that parse forms can do so. Form developers should not try
to set or alter these options.
The parsing program should insert reference options at the form
global level, page global level, and item level. Reference options
are not saved when the form is saved, and are stripped from the form
when it is submitted.
Syntax
reference_option = <page_tag> | <item_tag>
The following reference options are available:
Option name Setting Location in form
itemnext Item tag of the next item Each item description
in form's build order
itemprevious Item tag of the previous Each item description
item in the form's build
order
pagenext Page tag of the next page Each page global
in the form's build order
pageprevious Page tag of the previous Each page global
page in the form's build
order
itemfirst Item tag of the first item Each page global
in the current page
itemlast Item tag of the last item Each page global
in hte current page
pagefirst Page tag of the first page Form global
in the form description
pagelast Page tag of the last page Form global
in the form descrption
Universal Forms Description Language [page 27]
Note that the reference options refer to items that are next,
previous, first, or last in the form description. This may not be
the order in which items or pages appear on screen.
2.4l Operations
An operation is a calculation or a decision. The syntax of a
calculation is one of the following:
1. <operand> <math operator> <operand>
2. <operand>
Operands that are numbers can have a unary minus. An operand can be
any of the following:
- a literal (for example, "3")
- a reference to another option (for example, total_field.value)
- a calculation (for example, "total_field.value" *"4")
- (<decision>) - see below for the syntax of a decision
A math operator can be any of the following:
- additive operator
- multiplicative operator
- exponentiation operator
See the table of operators below.
The syntax of a decision is as follows:
<comparison> ? <expression> : <expression>
where <comparison> is:
- <Boolean> <logical operator> <Boolean>
and <Boolean> is:
- <operand> <relational operator> <operand>
Note: See the table below for the definition of logical and
relational operators. In decisions:
- An operand can have a logical NOT (!) before it.
- An expression cannot be an array.
Some examples of decisions are:
- A decision based on a check box.
male_check == "on" ? "male" : "female"
If the check box is selected, or on, then the result will be male.
Otherwise, the result will be female. This decision could be used to
set an item's value.
- A decision based on a value.
name_field == "Smith" ? "on" : "off"
If the name entered into the name field is Smith, then the result
will be on. Otherwise, the result will be off. This decision could
be used to set an item's active status.
The UFDL recognizes the following operators:
Type of Operator Symbol Operation
Universal Forms Description Language [page 28]
Additive + addition
- (minus) subtration
+. concatenation
Multiplicative * multiplication
/ division
Exponentiation ^ exponential
Relational > greater than
< less than
<= less than or equal to
>= greater than or equal to
== equal to
!= not equal to
Logical && AND
|| OR
! NOT
Unary Minus - (minus) take negative
Decision x?y:z Assign the value of expression
y to the result if expression
x evaluates to true.
Otherwise, assign the value of
expression z to the result
Assignment = Assign right operand to left
operand
Membership . (dot) structure membership
[ ] array membership
-> indirect membership
Precedence of Operations
Operations are evaluated in the following order:
- membership
- exponentiation*
- multiplicative and unary minus*
- additive
- relational
- logical NOT
- logical AND
- logical OR
- conditional
Operations at the same level of precedence are evaluated from left
to right.
Parentheses override the precedence levels; however, operations
within parentheses are evaluated using the normal precedence levels.
Universal Forms Description Language [page 29]
* When a unary minus immediately follows an exponentiation
symbol (^), the unary minus is evaluated first. For example,
10^-5 is evaluated as ten-to-the-minus-five.
Concatenation
An addition operation may imply concatenation. If either operand in
the addition contains a non-numeric value, the operands are
concatenated. Otherwise they are added arithmetically. You only need
to use the concatenation operator if both operands are, or can be,
numeric values.
The following examples demonstrate this rule:
"UFDL\\" + "form1" - yields "UFDL\\form1"
"UFDL\\form" + "1" - yields "UFDL\\form1"
"1" + "2" - yields "3"
"1" +. "2" - yields "12"
The last example would not have resulted in concatenation without
using the concatenation operator.
Separators
There are two separators in the UFDL: comma (,) and semicolon (;).
The comma separates list entries; the semicolon terminates an option
definition statement.
2.4m Arrays
The UFDL uses arrays to store values in options requiring multiple
settings. The number of elements and the number of dimensions in an
array depend on the option. However, the syntax of the language
supports n-elements and n-dimensions. Moreover, the UFDL supports
arrays containing a mix of simple elements and sub-arrays.
The syntax of an array is as follows:
[<element1>, <element2>, ... <elementn>]
Note: 'n' is the number of settings in the option.
An element can be either of the following:
- an expression
- an element definition statement
Element Definition Statements
The element definition statement allows you to assign a variable
name to an element. Variable names permit you to refer to the
element by name rather than by its position in the array. The syntax
of an element definition statement is:
<variable> = <expression>
Universal Forms Description Language [page 30]
The UFDL syntax includes variable names in some arrays. In this
case, you must use an element definition statement when assigning
values to the element. For example, the format option syntax
specifies names for the check option's range, length and template.
To assign values to any of these elements, you must use the name
specified in the syntax.
Examples of assignment statements using element definition
statements:
using a UFDL-defined variable name
format = ["integer", range=["1","100"]];
using a user-defined variable name
delay = [the_repeat = "once", the_time = "10"];
using both UFDL-defined and user-defined variable names
format = [the_type = "string", length = ["5", "25"]];
Array elements for UFDL-defined option types must be coded in the
position they are documented in this specification, unless they have
UFDL-defined variable names listed in this specification. For
example, the elements for the size option must always be in the
order [width, height], but the elements for check and format types
in the format option can be in any order, since they have UFDL-
defined variable names.
Decisions in Arrays
A decision can be used to determine any element within an array, so
long as that element is not itself an array.
For example, the following format line is valid.
format = [check_1.value == "on" ? "string" : "integer"];
The decision sets the data type to be a string if check_1 is "on",
or an integer if it is "off".
This format line is not valid:
format = ["integer", check_1 == "on" ? range = ["10","20"] : range =
["0","10"];
The range is itself an array, so a decision cannot be used to
determine which range should apply.
Array References
The syntax of an array reference is:
<array name>[<array element>]
Note: Repeat the phrase '[<array element>]' until reaching the
desired depth.
Array name is an option or variable identifier. Array element can be
one of two things:
- a number indicating the position of the element in the array
- variable name
Before using a variable name, you must define the name in an element
Universal Forms Description Language [page 31]
definition statement. See 'Element Definition Statements' in section
2.4m for more information.
The UFDL array starting position is 0; therefore, a reference to
the first element of the array is really a reference to element
zero (0).
The following examples show various array assignments and
references:
itemlocation = [["below", "field1"], ["alignl2l", "field2"],
["alignr2c", "field3"]];
itemlocation[0][1] - points to "field1"
itemlocation[2][0] - points to "alignr2c"
itemlocation = [the_pos= ["below", "field1"], the_align=
["alignl2l", "field2"]];
itemlocation[the_pos][1] - points to "field1"
itemlocation[the_align][0] - points to "alignl2l"
format = ["integer", range=["1","10"]];
format[0] - points to "integer"
format[range] - points to ["1", "10"]
format = ["integer", range=[the_low="1", the_high="10"]];
format[range][the_low] - points to "1"
2.4n Defining Tabbing and Paging
The UFDL provides two mechanisms for defining the movement between
pages and items in a form.
- tabbing to the new item or page
- linking to the new page
You can combine these methods or you can choose to use only one.
Tabbing permits the user to move from one item to another and from
one page to another using a keystroke. Linking permits the user to
select a form item whose action moves the focus to a new page.
Note: The only items users may tab or link to are modifiable items.
These are items users can change or select.
Tabbing
To use tabbing, define a tabbing sequence using the next option. The
sequence can include items anywhere in the form. Define the tabbing
sequence this way:
- Define the first item in the sequence by including the next
option in the form characteristics. When the form opens, the page
containing this item displays with the item that is in focus.
- Define each subsequent item by including the next option in the
definition of each item in the sequence.
The next option setting is the item reference of the next item to
receive focus (that is, the referenced item). When the user tabs
from the current item, the referenced item receives the focus. If
the item is on a different page, the current page closes and the
new page displays.
Universal Forms Description Language [page 32]
You can use tabbing to display a new page without choosing an item
to activate. Set the next option to the characteristics reference
for the new page. This displays the new page and focusses on the
first item in that page's tabbing sequence. The page characteristics
reference is <page tag>.global.
- Define the first item in a page's tabbing sequence by including
the next option in the page characteristics.
This example shows a simple tabbing sequence:
version = "3.2.0";
// Open the form on page 'page_one' and focus on 'title_list'.
next = "page_one.title_list";
page_one = new page
{
// Define the default first item in this page's tabbing
sequence.
next = "name_field";
bgcolor = ["224", "224", "224"];
form_title = new label
{
.......
}
title_list = new list
{
// Tab to the 'name_field' item from here.
next = "name_field";
......
}
name_field = new field
{
// Tab to the 'your_signature' item on 'page_two' from here.
next = "page_two.your_signature";
......
}
}
page_two = new page
{
bgcolor = ["240", "248", "255"];
form_title = new label
{
......
}
your_signature = new tablet
{
// Tab back to page 'page_one' and focus on the first item
// in the page_one tabbing sequence.
next = "page_one.global";
......
}
}
Universal Forms Description Language [page 33]
Linking
To use linking, define action, button, or cell items for the links
you want to include in the form, and set their type option to
pagedone. Since each item performs only one link, you require a
separate action, button, or cell for each link. This method is often
best suited to defining links to new pages.
When you link to a new page, do one of the following:
- Specify an item on the new page for the focus to move to.
- Specify that the focus move to the default position on the new
page, by "linking" to the page characteristics section.
Store the reference of the linked item or page in the url option of
the action, button, or cell. The reference is an item reference or a
page characteristics reference. Use an item reference when you want
to link a specific item. Use the page characteristics reference when
you want to link the first item in the page's tabbing sequence.
A page characteristics reference is <page tag>.global.
When the link occurs (i.e., a user selects the button), the current
page closes and the linked page appears. Before the current page can
close, all fields containing error checking must be correctly filled
in.
This example shows how you might use linking:
version = "3.2.0";
// Open the form on page 'page_one'.
Allow the first item in the page's
// tabbing sequence to receive focus.
next = "page_one.global";
page_one = new page
{
// Define the default first item in this page's tabbing sequence.
next = "name_field";
bgcolor = ["224", "224", "224"];
form_title = new label
{
.......
}
name_field = new field
{
......
}
next_page = new button
{
value = "Page 2";
// Link to the next page. Allow the first item in the page's
// tabbing sequence to receive focus.
type = "pagedone";
url = "#page_two.global";
......
}
}
Universal Forms Description Language [page 34]
page_two = new page
{
// Define the default first item in this page's tabbing sequence.
next = "your_signature";
bgcolor = ["240", "248", "255"];
form_title = new label
{
......
}
your_signature = new tablet
}
......
}
first_page = new button
{
value = "Page 1";
// Link to the first page. Allow the first item in the page's
// tabbing sequence to receive focus.
type = "pagedone";
url = "#page_one.global";
......
}
}
UFDL-Defined Default Paging and Tabbing Sequence
The UFDL-defined default sequence depends on the order in which you
define pages and items in the form. The default first page is the
first page defined in the form. The default first item is the first
item defined for the body of that page.
The sequence progresses through the page definition moving from one
modifiable item to the next. If a user tabs past the last modifiable
item on the page, focus returns to the first modifiable item in the
page's toolbar (if one exists) or the first modifiable item on the
page. The default sequence does not permit you to move between
pages.
The UFDL permits you to define pages and items in any order,
regardless of when and where they display. If you define your pages
and items in a random order, the default sequence may result in
apparently random movement.
2.4o Including External Files
You can code a #include statement anywhere in a form definition
except imbedded in another statement. You can also nest #include
statements. See section '6 UFDL Form Viewer Directive' for a syntax
of the #include statement.
In the following examples, you can see the #include statement used
in a variety of locations.
Universal Forms Description Language [page 35]
// Use the standard defaults for v3.2.0 forms. This include
file contains the // 'version' option statement and
the default 'url' option statement.
#include "v3form.txt"
page_one = new page
{
// Page one must contain the company logo. This include
file contains the // 'label' and 'data' item definitions.
#include "co_logo.txt"
// The remaining items are specific to this form.
...
}
// The last page is standard for all company forms.
Use the standard last // page definition.
# include "lst_page.txt"
}
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 items and options that contain the
non-compliances must be ignored when displaying the form.
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 items that contain
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.5 UFDL Language Elements
Universal Forms Description Language [page 36]
2.5a Identifiers
Identifiers are the names you assign to the following entities:
- page tags
- item tags
- option names
- variable names
- datagroup names
- group names
The naming conventions for an identifier are as follows:
- It must begin with an alphabetic character.
- It can contain any of the characters A-Z, a-z, 0-9, $ and
underscore.
An example of a valid identifier is sql_query.
2.5b Custom Item Types and Custom Option Names
These are the names you assign to your own items and options. The
naming conventions for a custom name are as follows:
- It must begin with an alphabetic character.
- It can contain any of the characters A-Z, a-z, 0-9, $ and
underscore.
- It must contain an underscore.
2.5c Reserved Words
The UFDL reserves the following words for its own use:
- UFDL item, option and variable names
- global
- page
- new
2.5d Quoted Strings
The syntax of a quoted string is:
"<character string>"
The minimum length of the string is one (1) byte; the maximum length
is the lesser of two gigabytes (231 - 1 bytes) and the amount of
memory the system will allocate.
Long quoted strings can span multiple lines. To code a multiple line
string, break the string into segments and surround each segment
with quotation marks. A reasonable segment length might be the
maximum line length permitted in your text editor.
The following example shows a multiple line quoted string in an
assignment statement. The UFDL treats the segments as contiguous,
ignoring any white space between them.
value = "This example demonstrates the use of quoted strings "
"that span multiple lines.";
Universal Forms Description Language [page 37]
Some characters, such as tabs and line delimiters, are invalid in a
quoted string unless you use an escape sequence. All escape
sequences begin with the escape character (\). The following table
shows the escape sequences the UFDL recognizes and the characters
they represent.
Escape Sequence Character Comments
\t tab The UFDL interprets this as
an imbedded tab character.
\n line delimiter The UFDL interprets this as
an imbedded line delimiter.
\xnn hexadecimal number The UFDL interprets 'nn' as
a hexadecimal number.
\mnn octal number If 'm' is 0, 1, 2 or 3, the
UFDL interprets 'mnn' as an
octal number.
\" double quote The UFDL interprets this as
an imbedded double quote mark.
\\ backslash The UFDL interprets this an
imbedded backslash.
\<any other> <any other> The UFDL ignores the escape
character.
2.5e Binary Data
Images and sounds are examples of binary data. Store binary data in
a form using the mimedata option of a data item. The mimedata option
requires a quoted string as its setting.
To store binary data in this manner, you must first convert it to
base64 format, copy the converted data into the form definition, and
insert the quotation marks. In all likelihood the data will span
several lines. Enclose each line in quotation marks.
Converting binary data to base64 format ensures the string contains
no characters requiring an escape sequence.
2.5f Comments
Comments must occur at the end of the line or on a line by
themselves. The UFDL supports two comment formats:
// comment - the comment ends at the end of the line
/* comment */ - these comments can span several lines
2.6 Processing Forms
Once a user saves or submits a form, it becomes a form instance.
In the course of a form instance's life cycle, it may be viewed by
Universal Forms Description Language [page 38]
various users at various client sites. Also, several form processing
applications may handle the form. To ensure consistency and
integrity of the form's appearance and contents, there are some
important form processing rules in the UFDL.
2.6a Include Statements
The rules governing handling of #include statements state:
- All #include statements are resolved when the form appears. The
only exception occurs when the referenced file cannot be found.
In this instance, the #include statement remains in the form.
- When a #include statement is resolved, the #include statement
definition is permanently deleted from the form instance.
These rules combine to ensure that the definition of a particular
form instance remains constant from first to last viewing, and that
no user data disappears.
2.6b Expressions
The rule governing handling of expressions in value options states:
( Expressions are overwritten if the item is modifiable and the
user updates the value displayed, or if the form submission format
is HTML.
This rule ensures that forms submitted in UFDL format continue to
work as originally designed even after processing.
3. UFDL Global and Page Settings
At the top of each form and each page, a form developer can specify
options that apply to the whole form or the particular page. These
are called global settings and page settings.
The syntax of global settings is as follows:
version = <version_number>;
<option definition2>
...
<option definitionn>
Notes:
i) The version option is mandatory. It must be the first line in
the form.
ii) All options other than version are optional.
iii) Global settings must appear before the first page declaration.
iv) A page setting can override a form global option for the
particular page.
The syntax of page settings is as follows:
<page tag> = new page
{
Universal Forms Description Language [page 39]
<option definition1>
...
<option definitionn>
Notes:
i) Page settings are optional.
ii) Page settings must appear before the first item definition in
the page.
iii) A page will assume the characteristics specified in the global
settings unless they are overridden by settings of the same
type in the page settings.
iv) Options within item declarations override page settings for the
particular item they appear in.
The following pages outline which options can be used as global
settings and which options can be used as page settings.
3.1 Global settings
Global settings specify particular settings for the form and
determine its physical characteristics. For example, the version
option defines which version of the UFDL the form was written in.
The bgcolor option determines the background color of all pages in
the form. Global settings appear at the top of a form and apply to
the whole form. Options defined within a page or item can override
global settings for that particular page or item.
Available Options
- bgcolor
- bordercolor
- borderwidth
- fontcolor
- fontinfo
- label
- next
- saveformat
- transmit
- transmitformat
- triggeritem
- version
Usage Notes
1) Define global settings at the top of the form, before the first
page declaration.
2) The version option is mandatory and must be the first line in
the form.
3) You can give the form a title that appears in the title bar by
setting a global label option.
4) If you define transmit as a global setting and set it to none,
the following will be transmitted:
Universal Forms Description Language [page 40]
- the form's global settings
- pages and items with transmit settings of all or filter
5) To specify a title to appear in the form's title bar, use the
label option as a global setting.
Example
This example defines settings and characteristics for the form.
version = "3.2.0";
saveformat = "application/uwi_form; content-encoding=\"gzip\" ";
label = "Time Sheet";
bgcolor = ["224", "224", "224"];
fontinfo = ["Helvetica", "10", "plain"];
These global settings specify that:
- The form is written in version 3.2.0 of the UFDL.
- All saves activated from the form should save the form as
a compressed UFDL form, unless specified otherwise in an
item that initiates a save.
- The title Time Sheet should appear in the title bar of all
pages, unless specified otherwise in a page global.
- All pages, toolbars, boxes, labels, and tablets should
have a grey background, unless they contain an option
specifying otherwise.
- All pages and items should use a plain, Helvetica, 10-point
font, unless they contain an option specifying otherwise.
(Note: Labels that are parts of other items, like fields,
are excluded from the fontinfo option. They are set using
the labelfontinfo option.)
3.2 Page settings
Page settings specify settings (like next and transmit) and
characteristics (like bgcolor) for the page they appear on. Page
settings appear at the top of each page definition, and apply to the
whole page. They can be overridden by option settings within items.
Available Options
- bgcolor
- bordercolor
- borderwidth
- fontcolor
- fontinfo
- label
- next
- saveformat
- transmit
- transmitformat
Usage Notes
1) Define page settings at the top of a page, after the opening
brace and before the first item declaration.
Universal Forms Description Language [page 41]
2) Page settings apply only to the page they are on.
3) Page settings are optional.
4) If you include a transmit option of none as a page setting,
only the following will be submitted:
- the page's settings
- any items with transmit settings of all or filter
5) To specify a title to appear in the page's title bar, use the
label option as a page setting.
Example
The following example shows page global options on two pages
within a single form.
...
page_1 = new page
{
bgcolor = ["224", "224", "224"];
next = "Name_field";
<item declaration>
...
}
page_2 = new page
{
fontinfo = ["Helvetica", "14", "plain"];
next = "Activity_popup";
<item declaration>
...
Page one would have a grey background, and would direct the focus
to the item called Name_field as soon as it opened. It would assume
the rest of its settings from the form's global settings. (If no
form global settings exist, the page will assume the UFDL defaults.)
On page two, the font would appear as plain, Helvetica, 14-point
type and the focus would be directed to the item called
Activity_popup as soon as the page opened. Page two would assume
the rest of its settings from the page global options and UFDL
defaults.
4. UFDL Form Items
Items are the basic elements of a page. The syntax of an item
definition is as follows:
<item tag> = new <item type>
{
<option definition1>
...
Universal Forms Description Language [page 42]
<option definitionn>
}
Notes:
i) The braces are mandatory.
ii) An item definition must begin on a new line.
iii) Option definitions are optional.
iv) You cannot assign values to options in other item definitions.
The item tag uniquely identifies an item instance. No two item tags
on a page can be the same. Item type is a name that identifies the
type of item. This section contains information about the
UFDL-defined item types and the options available for each.
Note: Defining an option more than once in an item's definition may
cause unpredictable behaviour.
See section '2.4d Item Definition' for more information on the
syntax and rules regarding an item definition.
4.1 Action
The action item allows you to specify 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 option section for a description of each of these
actions.
You can define action items that occur only once or repeat at
specified time intervals. You can also define actions that 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.
Available Options
You may use the following options with action:
- active
- datagroup
- delay
- transmit
- transmitformat
- transmititems
- transmitoptions
Universal Forms Description Language [page 43]
- type
- url
Usage Notes
1) 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.
2) Actions, by the form definition rules, reside on a page;
therefore, actions occur only when the page is open, and
repeating actions stop when a the page closes. Actions defined
to occur before the page displays, occur each time the page
opens.
Examples
Example 1
The following action will send a status message to the server. The
transaction happens automatically every 10 minutes (600 seconds).
sendStatus_action = new action
{
delay = ["repeat", "600"];
type = "submit";
url = ["http://www.server.com/cgi-bin/recv_status"];
}
Example 2
This action will link to a search form as soon as the current page
displays.
grabSearch_action = new action
{
delay = ["once", "0"];
type = "link";
url = ["http://www.server.com/application/index/search.frm"];
}
Example 3
Background actions can also cancel forms, or prompt the user to
save a form. Here is an example:
// Automatically prompt the user to save the form after 5 minutes
autoSave_action = new action
{
delay = ["once", "300"];
type = "save";
}
//
// Automatically close the form after 10 minutes
autoCancel_action = new action
Universal Forms Description Language [page 44]
{
delay = ["once", "600"];
type = "cancel";
}
4.2 Box
The box item creates a square box on the form. You may not place
other items in the box; however, you may place other items on top
of it. The purpose of box items is simply to add visual variety to
the form.
Available Options
You may use the following options with box:
- bgcolor
- bordercolor
- borderwidth
- fontinfo
- itemlocation
- size
- transmit
Usage Notes
1) To make the box more visible, assign a background color that
differs from the page background color (the default).
2) 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).
Example
The following example shows a typical box description. The box is 25
characters wide and 4 characters high. Notice the background color
setting.
blue_box = new box
{
bgcolor = ["0", "0", "255"];
size = ["25", "4"];
}
4.3 Button
The button item provides a click button to perform an action when
selected. For example, you can use buttons to request data from
a web server, submit or cancel the form, save the form to disk, or
enclose external files.
Available Options
You may use the following options with button:
- active
Universal Forms Description Language [page 45]
- bgcolor
- bordercolor
- borderwidth
- coordinates
- datagroup
- fontcolor
- fontinfo
- help
- image
- itemlocation
- justify
- next
- size
- transmit
- transmitformat
- transmititems
- transmitoptions
- type
- url
- value
Usage Notes
1) The button's label is defined by the value option. If no value
option exists, the default label is blank.
2) 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).
Examples
Example 1
This button links the form to a server (www.server.com) and
retrieves a form called fromHelp.frm.
getHelp_button = new button
{
value = "Get Help";
type = "link";
url = ["http://www.server.com/application/help/formHelp.frm"];
}
Example 2
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:
submit_button = new button
{
value = "Process Form";
fontinfo = ["Helvetica", "18", "bold", "italic"];
type = "submit";
url = ["http://www.server.com/cgi-bin/formProcessor"];
Universal Forms Description Language [page 46]
}
Example 3
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:
enclose_button = new button
{
value = "Enclose File";
fontinfo = ["Helvetica", "18", "bold", "italic"];
type = "enclose";
datagroup = ["Images_Asia", "Images_Eur" , "Images_SAmer"];
}
This button will allow users to enclose files into one of three
datagroups (folders): Images_Asia, Images_Eur, Images_SAmer.
4.4 cell
The cell item 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 behaviour:
- Action cells
These cells perform the same set of actions normally
associated with buttons. This includes such things as
cancelling, saving and submitting the form.
- Select cells
These cells provide users with a mutually exclusive set
of values from which to choose. When chosen, these cells
appear selected. In a list this means the cell is
highlighted in some way. In a popup, the cell's label
becomes the popup's label.
Available Options
You may use the following options with cell:
- active
- datagroup
- group
- label
- transmit
- transmitformat
- transmititems
- transmitoptions
- type
- url
- value
Universal Forms Description Language [page 47]
Usage Notes
1) Use the type option to establish a cell's behaviour. Select
cells that have a type of select (the default type).
2) 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.
3) 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.
4.5 check
The check item 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[PD1] dependent;
but the shape is rectangular. The check box appears as a normal
check box for the users of each platform.
Available Options
You may use the following options with check:
- active
- bgcolor
- bordercolor
- editstate
- fontcolor
- fontinfo
- help
- itemlocation
- label
- labelbgcolor
- labelbordercolor
- labelborderwidth
- labelfontcolor
- labelfontinfo
- next
- size
- transmit
- value
Usage Notes
1) 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
Universal Forms Description Language [page 48]
value is off.
2) Check boxes do not belong to groups like radio buttons-each
check box may be turned on or off independently of the others.
3) The label option defines the label for the check box. The label
appears above the check box and aligned with the boxes left
edge. There is no default label.
4) 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).
5) The fontcolor option determines the color of the check box fill
pattern (default is red).
Example
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.
healthPlan_check = new check
{
value = "on";
label = "Activate Health Plan";
labelfontinfo = ["Times", "14", "bold"];
labelfontcolor = ["0", "0", 255"];
}
4.6 combobox
Comboboxes act like a hybrid of a field and a popup. Unopened, a
combobox with a label occupies the same space 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.
Available Options
You may use the following options with combobox:
- active
- bgcolor
- bordercolor
- borderwidth
- editstate
- fontcolor
- fontinfo
Universal Forms Description Language [page 49]
- format
- group
- help
- itemlocation
- label
- labelbgcolor
- labelbordercolor
- labelfontcolor
- labelfontinfo
- next
- size
- transmit
- value
Usage Notes
1) 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.
2) 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.
3) Combobox, popup, and list items with the same group reference
display the same group of cells.
4) When first viewed, a combobox will display its value. If no
value is set, the combobox will be empty.
5) 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.
6) 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).
7) The label option sets the text displayed above the item,
as with a field.
8) 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 write only 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.
Universal Forms Description Language [page 50]
9) 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.
10) If any two comboboxes, lists, or popups use the same set of
cells, they must apply the same formatting.
Example
This is an example of a combobox containing a set of selections
allowing users to choose a color.
CATEGORY_POPUP = new combobox
{
group = "combo_Group";
label = "Choose a Color:";
}
Notice 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. Notice they are
select cells and they belong to the same group as the combobox:
combo_Group.
RED_CELL = new cell
{
group = "combo_Group";
type = "select";
value = "Red";
}
WHITE_CELL = new cell
{
group = "combo_Group";
type = "select";
value = "White";
}
BLUE_CELL = new cell
{
group = "combo_Group";
type = "select";
value = "Blue";
}
4.7 data
The data item stores an information object such as an image,
a sound, or an enclosed file in a UFDL form. Data in data items
must be encoded in base64 format.
Universal Forms Description Language [page 51]
Data items are created automatically when you enclose files in a
form. Enclose files using items with a type option setting of
enclose.
Available Options
You may use these options with data:
- datagroup
- filename
- mimedata
- mimetype
- transmit
Usage Notes
1) See section '2.5e Binary Data' for more information
on binary data in UFDL forms.
2) Store the data in the mimedata option, and the data's MIME type
in the mimetype option.
Example
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). Notice the quotation marks
surrounding each segment of the data.
Supporting_Documents_1 = new data
{
filename = "smithltr.doc";
datagroup = ["Supporting_Documents"];
mimetype = "application/uwi_bin";
mimedata =
"R0lGODdhYABPAPAAAP///wAAACwAAAAAYABPAAAC/4SPqcvtD02Y"
"Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrS2YzmTE+p"
"yai3YUk9R6hee2JFP2stju+uG0ptvdeKptb+cX8wfY1jdYU4ehKDi3pdJw"
"44yAJEqcW28cA5M0oEKnqKasZwydrK9Wo6JTtLG9p5iwtWi8Tbi/b7E0"
"rvKixzbHJyrDq2uNggaXUs1NlLi36AW3AGv7VWhIPA7TzvdOGi/vvr0Of"
"ft3Nrx89JewCQJYTirxi2PwgnRpNoMV5FIIboOnqTszFLFIMhQVI0yOz";
}
4.8 field
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.
Universal Forms Description Language [page 52]
Available Options
You may use the following options with field:
- active
- bgcolor
- bordercolor
- borderwidth
- editstate
- fontcolor
- fontinfo
- format
- help
- itemlocation
- label
- labelbgcolor
- labelbordercolor
- labelborderwidth
- labelfontcolor
- labelfontinfo
- next
- scrollhoriz
- scrollvert
- size
- transmit
- value
Usage Notes
1) 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).
2) The editstate option determines whether the field is
read only, write only (for passwords, for example) or
available for both reading and writing.
3) The format option specifies the data type of the field's
data. It also contains flags allowing you to specify edit
checks and formatting you want applied to the data.
4) The label option defines the field's label. The label is
placed above the field and aligned with the field's left edge.
5) 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.
Examples
Example 1
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
Universal Forms Description Language [page 53]
the field. When the form appears, the field will contain this value.
income_field = new field
{
label = "Annual income";
value = "23000";
size = ["20", "1"];
fontinfo = ["Courier", "12", "plain"];
labelfontinfo = ["Helvetica", "12", "plain"];
labelfontcolor = ["0", "0", "255"];
}
Example 2
To create a multiple line field, the vertical size of the field
must be adjusted (either with size or with itemlocation modifiers).
As well, vertical scroll bars can be added, and word wrapping
turned on. Here is an example:
job_field = new field
{
label = "Job Description";
size = ["50", "5"];
scrollvert = "always";
scrollhoriz = "wordwrap";
fontinfo = ["Times", "12", "plain]";
labelfontinfo = ["Helvetica", "12", "plain"];
labelfontcolor = ["0", "0", "255"];
}
4.9 help
A help item defines a help message you can use to support various
external items in the form. You can create a separate help item for
every item you want to support, or you can use one help item for
several items.
Available Options
You may use these options with help:
- active
- transmit
- value
Usage Notes
1) The help item's value option contains the help message text.
2) 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.
Example
Universal Forms Description Language [page 54]
This is an example of a button for which help information is
available. First, here is the button definition. Notice the help
item's item reference in the help option.
fullPicture_button = new button
{
value = "View Full-Sized Picture";
help = "button_help";
fontinfo = ["Times", "14", "plain"];
type = "link";
url = ["http://www.server.com/application/fullPic.frm"];
}
Now, here is 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.
button_help = new help
{
value = "Pressing this button will bring a full-sized image in a
form "
"down to your viewer.";
}
4.10 label
The label item 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.
Available Options
You may use the following options with label:
- active
- bgcolor
- bordercolor
- borderwidth
- fontcolor
- fontinfo
- format
- help
- image
- itemlocation
- justify
- size
- transmit
- value
Usage Notes
1) To define the text for a label, use the value option. To
define an image for a label, use the image option.
2) To create a multiple line text message, add line breaks
to the message text. Use the escape sequence '\n' to
Universal Forms Description Language [page 55]
indicate a line break.
3) 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).
Examples
Example 1
This is an example of a text label. The text is centered in the
space the label occupies. The label width is 30 characters
(thus it is bigger than the text in the label).
MAINMENU_LABEL = new label
{
value = "Welcome to the Main Menu";
fontinfo = ["Helvetica", "24", "bold", "italic"];
size = ["30", "1"];
justify = "center";
}
Example 2
This is an example of a multiple line text label. Notice the line
break escape sequences indicating the end of each line.
// Specify right justification for this label.
RHYME_LABEL = new label
{
value = "Little miss Muffet\n Sat on her tuffet,\n"
"Eating her curds and whey.\n When along came a
spider,\n" "who sat down beside her,\n and frightened
miss Muffet away!";
fontinfo = ["Times", "16", "italic"];
}
4.11 line
The line item draws a simple vertical or horizontal line on the
form. This is useful when you want to visually separate a parts of
a page.
Available Options
You may use the following options with line:
- fontcolor
- fontinfo
- itemlocation
- size
- thickness
- transmit
Usage Notes
1) Specify the dimensions of a line using the size and thickness
Universal Forms Description Language [page 56]
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.
2) 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.
3) The fontcolor option defines the color of the line.
Example
This is an example of a horizontal line with a thickness of five
pixels.
BLUE_LINE = new line
{
size = ["40", "0"];
thickness = "5";
fontcolor = ["0", "0", "255"];
}
4.12 list
The list item 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.
Available Options
You may use the following options with list:
- active
- bgcolor
- bordercolor
- borderwidth
- editstate
- fontcolor
- fontinfo
- group
- help
- itemlocation
- label
- labelbgcolor
- labelbordercolor
- labelborderwidth
- labelfontcolor
Universal Forms Description Language [page 57]
- labelfontinfo
- next
- size
- transmit
- value
Usage Notes
1) 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.
2) Cells that have a label option will display that label in the
list. Otherwise, the value option of the cell will be displayed.
3) List, combobox and popup items with the same group reference
display the same group of cells.
4) 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".
5) Define the list's label using the label option.
6) 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).
7) 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.
8) 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.
9) If any two comboboxes, lists, or popups use the same set of
cells, they must apply the same formatting.
Example
This is an example of a list containing three actions: submit form,
save form, and cancel form.
Here is the list definition.
MAINMENU_LIST = new list
{
group = "list_Group";
label = "Options Menu";
Universal Forms Description Language [page 58]
labelfontcolor = ["0", "0", "255"];
size = ["3", "20"];
}
These are the cells that make up the list. Notice they are action
cells and they belong to the same group as the list: list_Group.
SUBMIT_CELL = new cell
{
group = "list_Group";
type = "submit";
url = ["http://www.server.com/cgi-bin/processForm"];
value = "Submit Form";
}
SAVE_CELL = new cell
{
group = "list_Group";
type = "save";
value = "Save Form";
}
CANCEL_CELL = new cell
{
group = "list_Group";
type = "cancel";
value = "Cancel this Form";
}
4.13 popup
The popup item 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.
Available Options
You may use the following options with popup:
- active
- bgcolor
- bordercolor
- borderwidth
- editstate
- fontcolor
- fontinfo
Universal Forms Description Language [page 59]
- group
- help
- itemlocation
- justify
- label
- next
- size
- transmit
- value
Usage Notes
1) 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.
2) 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.
3) Popup, combobox and list items with the same group reference
display the same group of cells.
4) 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".
5) 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).
6) 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.
7) 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.
8) If any two comboboxes, lists, or popups use the same set of
cells, they must apply the same formatting.
Example
This is an example of a popup containing a set of selections
Universal Forms Description Language [page 60]
allowing users to choose a category.
Here is the popup definition. Notice 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.
CATEGORY_POPUP = new popup
{
group = "popup_Group";
label = "Choose a Category:";
}
These are the cells that make up the popup. Notice they are
select cells and they belong to the same group as the popup:
popup_Group.
HISTORY_CELL = new cell
{
group = "popup_Group";
type = "select";
value = "World History";
}
SCIENCE_CELL = new cell
{
group = "popup_Group";
type = "select";
value = "Physical Sciences";
}
MUSIC_CELL = new cell
{
group = "popup_Group";
type = "select";
value = "Music";
}
4.14 radio
The radio button item is 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.
Available Options
You may use the following options with radio:
- active
- bgcolor
Universal Forms Description Language [page 61]
- bordercolor
- editstate
- fontcolor
- fontinfo
- group
- help
- itemlocation
- label
- labelbgcolor
- labelbordercolor
- labelborderwidth
- labelfontcolor
- labelfontinfo
- next
- size
- transmit
- value
Usage Notes
1) 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.
2) 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.
3) 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.
4) The label option defines a label to appear above the radio
button and aligned with its left edge.
5) 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).
6) The fontcolor option determines the color of the radio button
fill pattern (default is red).
Example
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.
NAME_RADIO = new radio
{
value = "on";
group = "search_Group";
label = "Search by Name";
Universal Forms Description Language [page 62]
}
NUMBER_RADIO = new radio
{
group = "search_Group";
label = "Search by Number";
}
OCCUPATION_RADIO = new radio
{
group = "search_Group";
label = "Search by Occupation";
}
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.
4.15 spacer
The spacer item creates space between items on a form. It can be any
size you specify. It is invisible.
Available Options
You may use these options with spacer:
- fontinfo
- itemlocation
- label
- size
- transmit
Usage Notes
1) You can size a spacer either by giving it length and width
dimensions (using size), by expanding the default size using
the item location option or by giving it a label. If you use
a label, the spacer equals the size of the text you type into
the label. The label does not appear; it is simply used to
determine the spacer's size.
2) 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).
Example
Example 1
This example shows a spacer item that uses the size option to
define the amount of space it will occupy.
3_SPACER = new spacer
{
size = ["1", "3"];
}
Universal Forms Description Language [page 63]
Example 2
This example shows the spacer item that uses a label to define
the amount of space it will occupy. This sizing technique is useful
if you want to create a spacer that is exactly the same size as
a real label on the form.
WELCOME_SPACER = new spacer
{
label = "Welcome to Information Line";
}
4.16 tablet
The tablet item creates a rectangular space or drawing object
on the page where users can draw or write using the mouse pointer.
This allows users to do such things as sign the form.
To draw on a tablet, users hold down the left mouse button while
moving the mouse pointer over the space. To erase the marks,
users position the mouse over the tablet, hold down CONTROL
and click the right mouse button.
The tablet's background may be blank or composed of an image.
The user draws on the background.
Available Options
You can use the following options with tablet:
- active
- bgcolor
- bordercolor
- borderwidth
- fontcolor
- fontinfo
- help
- image
- itemlocation
- justify
- next
- size
- transmit
- value
Usage Notes
1) A tablet item must contain an image option that associates
it with a data item. The data item must also exist in the form.
The user's drawing marks will be stored as image data in the
data item.
For example, this is the code necessary to create a blank tablet
(that contains no image background) on a form.
sketch_tablet = new tablet
Universal Forms Description Language [page 64]
{
fontcolor = ["0", "0", "255"];
size = ["30", "5"];
image = "sketch_data";
}
...
sketch_data = new data
{
}
2) To place an image in a tablet's background, store the image
data in the data item already associated with the tablet.
Note that when the user draws on the tablet, the user's
marks will be stored as part of the same image.
For example, this piece of sample form code shows a tablet that
contains an image called sign_data.
sign_tablet = new tablet
{
fontcolor = ["0", "0", "255"];
size = ["30", "5"];
image = "sign_logo";
}
...
sign_data = new data
{
mimedata = "R0lGODdhYABPAPAAAP///wAAACwAAAAAYABA/"
"Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrSzTE+p"
"yai3YUk9R6hee2JFP2stju+uG0ptvdeKptb+cX8wfY1jdYU4KpdJw"
"44yAJEqcW28cA5M0oEKnqKasZwydrK9Wo6JTt9p5iwt8bi/b7E0"
"rvKixzbHJyrDq2uNggaXUs1NlLi36AW3AGv7VWhIPAzvdGi/vvr0Of"
"ft3Nrx89JewCQJYTirxi2PwgnRpNoMV5FIIboOnqTszFMhVI0yOz";
}
3) The fontcolor option determines the pen color.
4) The pen width is two pixels.
5) The value can be used to set the initial size of the tablet.
If no size is indicated, and no mimedata exists, the tablet
will size itself to the size of the text entered in the value.
Example
This example shows a blank tablet with a background color of pale
green. It is 40 characters wide and 10 characters high.
users_signature = new tablet
{
bgcolor = ["152", "251", "152"];
size = ["40", "10"];
fontinfo = ["Courier", "12"]; // This governs the size.
Universal Forms Description Language [page 65]
fontcolor = ["0", "0", "0"]; // This governs pen color.
image = "signature_data";
}
signature_data = new data
{
}
4.17 toolbar
The toolbar item allows you to define a toolbar for your 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, you place items in the toolbar that you want users
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, you will have to scroll to see everything it contains.
Refer to section '2.3a Toolbars' for more information
on toolbars.
Available Options
You can use the following options with toolbar:
- bgcolor
- transmit
All options default to the characteristics of the page body.
Note: The transmit option refers to the toolbar item, not the
items the toolbar contains.
Usage Notes
1) The background color of the toolbar becomes the default
background color for items in the toolbar.
2) Add items to the toolbar using the within modifier of the item
location option. Code the itemlocation option in each included
item's definition.
Example
This example shows a toolbar that contains a label, a spacer, and
two buttons.
Here is the toolbar definition:
TOOL_BAR = new toolbar
{
bgcolor = ["224", "224", "224"];
}
Here are the items belonging to the toolbar.
Universal Forms Description Language [page 66]
COMPANY_NAME = new label
{
value = "My Company";
item location = [["within", "TOOL_BAR"]];
}
TB_SPACER = new spacer
{
itemlocation = [["within", "TOOL_BAR"], ["below",
"COMPANY_NAME"]];
}
SUBMIT_BUTTON = new button
{
value = "Submit Form";
type = "submit";
url = ["http://www.server.com/cgi-bin/formProcessor"];
itemlocation = [["within", "TOOL_BAR"], ["below", "TB_SPACER"]];
}
CANCEL_BUTTON = new button
{
value = "Cancel Form";
type = "cancel";
itemlocation = [["within","TOOL_BAR"], ["after",
"SUBMIT_BUTTON"]];
}
4.18 <custom item>
Custom items allow form designers to add application specific
information to the form definition. This is useful when submitting
forms to applications requiring non-UFDL information. An example
of non-UFDL information might be an SQL query statement.
Available Options
You can use all UFDL options and any custom options with custom
items.
Usage Notes
1) The naming conventions for a custom item are as follows:
- It must begin with an alphabetic character.
- It can contain any of the characters A-Z, a-z, 0-9, $ and
underscore.
- It must contain an underscore.
Example
This is an example of a custom item definition. It includes both
a UFDL and a custom option.
STATUS_EVENT = new ma_event
{
active = "off";
ma_id = "UF45567 \t /home/users/preferences01";
}
Universal Forms Description Language [page 67]
5. UFDL Form Options
An option defines a characteristic of a form, a page, or an
item. An option definition is an assignment statement.
The expression on the right hand side of the equal sign
contains the option's setting. The syntax of an option definition
statement is as follows:
<option identifier> = <expression>;
Note: The semicolon is mandatory and terminates the statement.
Option identifier is a name that identifies the type of option.
It can be a UFDL-defined option or a custom option. Examples of
option identifier are: bgcolor, fontinfo, itemlocation, and size.
See section '5 UFDL Form Options' for a description
of each option and its possible values.
An expression specifies a value. An expression can be any of the
following:
- a literal
- a reference to another option definition in the form
- an operation
- an array specification
Use an array specification for options requiring or permitting
multiple values. The syntax of an array specification is
as follows: [PD2]
[<element1>, <element2>, ... <elementn>]
Note: 'n' is the number of settings in the option.
An element can be any of the following:
- an expression
- an element definition statement
The brackets surrounding the array specification are mandatory
even when there is only one element in the list.
The evaluation of array elements is done in their order of position
unless the elements have UFDL-defined variable names. See the
following section for a discussion of variable names.
Element Definition Statements
The element definition statement allows you to assign a variable
name to an array element. Variable names permit you to refer to the
element by name rather than by its position in the array. The syntax
of an element definition statement is:
<variable> = <expression>
See section '2.4h Option Definition' for more information on
expressions and arrays.
Universal Forms Description Language [page 68]
Characteristics
Options set for the form or a page are called characteristics. Form
characteristics are global to the entire form. Page characteristics
are global to the page on which they occur.
Defining Form Characteristics
Defining form characteristics is optional. It has the effect of
setting characteristics that are global to the form. These
characteristics override the defaults defined by the UFDL. Specific
pages or items will override these global characteristics if the same
option is set differently for that page or item.
Use the reference global.global when referring to form
characteristics.
Defining Page Characteristics
Defining page characteristics is also optional. It has the effect of
setting characteristics that are global to the page. These settings
override the defaults defined by the UFDL and any form
characteristics. Specific pages or items will override these global
characteristics if the same option is set differently for that page
or item.
Use the reference global or <page tag>.global when referring to page
characteristics.
Item Reference
An item reference identifies a particular item instance. The syntax
of an item reference is as follows:
- for items on the current page
<item tag>
- for items on another page
<page tag>.<item tag>
Data Type Designators
The UFDL defines a set of data types to describe the variable data
in option settings. Each option's description includes the necessary
data type information. The UFDL uses the following data type
designators:
Data Type Description
char a single ASCII character
string a series of ASCII characters
color an RGB triplet representing the color
- The syntax of an RGB triplet is: [<red>,
<green>, <blue>]. For example, the triplet for
Universal Forms Description Language [page 69]
green is:["0", "255", "0"].
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 to 65,535
Syntax Notation Conventions
The following syntax notation conventions have been used in the
sections following:
- Names have been assigned to each expression on the right hand
side of the assignment operator (=). The meaning and setting of
each expression appear in a table below the syntax diagram.
For example:
fontinfo = [<font name>, <point size>, <weight>, <effects>,
<form>];
Note: <weight>, <effects>, and <form> are optional.
Expression Setting Description
<font name> string the name of the font
<point size> short int the size of the font
<weight> "plain" use plain face
"bold" use bold face
<effects> "underline" underline the text
<form> "italics" use the italic form
- In the table, the Setting column indicates whether the
expression requires variable data or a constant value.
Variable data is represented by a data type; a constant
value is represented by the required keyword. Data types
appear in italics (for example, string); constants display
in bold face (for example, underline).
- A set of mutually exclusive choices is represented by a
list of settings beside an expression's name in the table.
For example, in the fontinfo statement, the <weight>
expression can be one of plain or bold.
- The syntax of an expression can take many forms. For example,
the following formats are all valid:
Universal Forms Description Language [page 70]
value = "Sample expression";
value = field_one.value;
value = "Sample " +. field_two.value;
As a consequence of the variation, syntax diagrams make no reference
to an expression's format.
See section '2.4h Option Definition' for a discussion of
expression formats.
- Repeating expressions are represented using an <opt1>, ... <optn>
notation and an explanatory note. For example,
datagroup = [<datagroup reference1>, ... <datagroup referencen>];
Note: Include a <datagroup reference> entry for each datagroup this
item accesses.
- Optional expressions are noted in an explanatory note. For
example, fontinfo = [<font name>, <point size>, <weight>,
<effects>, <form>];
Note: <weight>, <effects> and <form> are optional.
5.1 active
The active option specifies whether an item is active or inactive.
Inactive items do not respond to user input and, if possible, appear
dimmed.
For example, an inactive check box will be dimmed and the user will
not be able to select or deselect the box.
Syntax
active = <status>;
Expression Setting Description
<status> "on" item is active
"off" item is inactive
Available In
- action
- button
- cell
- check
- field
- help
- label
- list
- popup
- radio
- tablet
Example
Universal Forms Description Language [page 71]
This sample specifies the item is active.
active = "on";
Usage Notes
1) Default: on
2) Setting active to off would be similar to setting an edit
state of readonly.
5.2 bgcolor
The bgcolor option defines the background color of a page or an
item.
Syntax
bgcolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See ' 5 UFDL Form
Options;Data Type Designators for the
syntax of an RGB triplet.
Available In
- box
- button
- check
- field
- list
- popup
- radio
- tablet
- toolbar
- page global characteristics
- form global characteristics
Examples
This sample sets the background color to forest green.
bgcolor = ["34", "139", "34"];
Usage Notes
1) Default: varies depending on the object
Page: ["255", "255", "255"]; (white)
Item: depends on the item type
- button items: ["192", "192", "192"]; (grey)
- check, field, list, popup, and radio items: ["255",
"255", "255"]; (white)
- all other items: the page background color
Universal Forms Description Language [page 72]
5.3 bordercolor
The bordercolor option defines the color of the border around
the item.
Syntax
bordercolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See
'5 UFDL Form Options;Data Type
Designators' for the syntax
of an RGB triplet.
Available In
- box
- button
- check
- field
- list
- popup
- radio
- tablet
- page global characteristics
- form global characteristics
Examples
This sample sets the border color to light blue.
bordercolor = ["173", "216", "230"];
Usage Notes
1) Default: ["0", "0", "0"]; (black)
5.4 borderwidth
The borderwidth option defines the width of an item's border.
The unit of measurement is pixels.
Syntax
borderwidth = <width>;
Expression Setting Description
<width> short int the width of the border
Universal Forms Description Language [page 73]
Available In
- box
- button
- field
- label
- list
- popup
- tablet
- page global characteristics
- form global characteristics
Example
This sample sets the border width to five pixels.
borderwidth = "5";
Usage Notes
1) Default: varies depending on the item type
- box and label items: zero pixels
- all other visible items: one pixel
5.5 coordinates
The coordinates option records the position of the mouse pointer on
an image. The image must exist in a button item. The recording
occurs when a user selects (i.e. clicks) the button using the mouse
pointer.
The position is an intersection on an unseen grid overlaying the
image. The points along each axis of the grid range from zero (0)
through 1000 with position 0,0 occurring in the top, left corner.
The coordinates map the intersection closest to the mouse pointer's
position.
Syntax
coordinates = [<X_coordinate>, <Y_coordinate>];
Expression Setting Description
<X_coordinate> coordinate the coordinate on the X axis
<Y_coordinate> coordinate the coordinate on the Y axis
Available In
- button
Example
When a user clicks on a button containing an image, a coordinates
option statement is inserted into the button definition. The
statement would look something like this. This particular setting
Universal Forms Description Language [page 74]
indicates a position at the intersection of points 180 on the x-axis
and 255 on the y-axis.
coordinates = ["180", "255"];
Usage Notes
1) Default: none
5.6 datagroup
The datagroup option identifies a group or folder of enclosed files.
Each enclosed file can belong to several datagroups, and each
datagroup can contain several enclosed files.
Syntax
datagroup = [<datagroup reference1>, ... <datagroup referencen>];
where <datagroup reference> is one of:
- <datagroup name> for datagroups on the current page
- <page tag>.<datagroup name> for datagroups on other pages
Note: Include a <datagroup reference> entry for each datagroup
this item accesses.
Expression Setting Description
<datagroup reference> string identifies a datagroup
Available In
- action
- button
- cell
- data
Example
If this sample were part of a data item definition, it would mean
the data item belonged to the datagroups: Business_Letters,
Personal_Letters, and Form_Letters.
If this sample were part of a action, button, or cell item, it would
mean the user could store the enclosure in one of the three
datagroups.
datagroup = ["Business_Letters", "Personal_Letters",
"Form_Letters"];
Usage Notes
1) Default: none
2) Used with items handling enclosures, datagroup lists the
Universal Forms Description Language [page 75]
datagroups the item can access. Used with a data item,
datagroup lists the datagroups to which the enclosure belongs.
Enclosures are stored in data items.
3) Items that handle enclosed files perform enclose, extract,
remove, and display actions. These actions types are set
using the type option.
4) When a user selects an item that handles enclosed files, the
list of datagroups appears. The user chooses the datagroup
(or folder) with which to work. If the action is enclosing,
the enclosed file is added to that datagroup. Otherwise, a
list of files in the datagroup appears. The user chooses a
file from the list.
5) The action of enclosing a file creates the data item, and
stores the user's choice of datagroup (or folder) in the data
item's datagroup option.
5.7 delay
The delay option delays the execution of an automatic action or
specifies an automatic action repeat factor. Repeated actions stop
when the page containing the action definition closes. Define
automatic actions using an action item.
Syntax
delay = [<repeat factor>, <interval>];
Expression Setting Description
<repeat factor> "repeat" queue the action to repeat at the
<interval> specified
"once" perform the action once after the
<interval> specified
<interval> integer the frequency of repeated actions or
the delay before performing single
occurrence actions. The unit of
measurement is seconds.
"-1" perform the action before the page
displays. Only valid with a repeat
factor of once.
Available In
- action
Example
This sample sets the action to occur once, 15 minutes (900 seconds)
after the page opens.
Universal Forms Description Language [page 76]
delay = ["once", "900"];
Usage Notes
1) Defaults:
- repeat factor: once
- interval: zero seconds
This means the action will occur when the page appears.
2) 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.
3) All actions with the same interval occur in the order they are
defined in the page.
4) The page does not display while actions with an interval of
-1 are running.
5.8 editstate
The editstate option defines one of three possible edit states for
modifiable items.
Syntax
editstate = <edit state>;
Expression Setting Description
<edit state> "readonly" users cannot change the item's
setting
"writeonly" users can change, but not see,
the item's setting
"readwrite" users can see and change the
item's setting
Available In
- check
- field
- list
- popup
- radio
Example
This sample sets the editstate to readonly.
editstate = "readonly";
Usage Notes
Universal Forms Description Language [page 77]
1) Default: readwrite.
2) The writeonly setting applies only to fields. It causes all
characters the user types to appear the same as the system
password character.
3) The readonly setting permits users to scroll an item even though
they may not update the item's contents.
5.9 filename
The filename option identifies the name of an enclosed file. This
name appears in the list of enclosed files.
Syntax
filename = <file name>;
Expression Setting Description
<file name> string the name of the enclosed file
Available In
- data
Example
This sample specifies the name of an enclosed file.
filename = "std_logo.frm";
Usage Notes
1) Default: none
2) To ensure cross-platform compatibility, you should limit
filenames to the following set of characters: lowercase
letters from a to z, uppercase letters from A to Z, the
integers 0 through 9, and the underscore (_).
3) To ensure cross-platform compatibility, you should limit form
names to a maximum of eight characters, followed by a .frm
extension.
5.10 fontcolor
The fontcolor option defines the font color for the text or filler
portion of an item. In radio and check items, fontcolor defines the
color of the bullet and check, respectively. In line items,
fontcolor defines the color of the line. In tablet items, fontcolor
defines the pen color. In other items, it defines the text color.
Syntax
Universal Forms Description Language [page 78]
fontcolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See '5 UFDL Form
Options;Data Type Designators' for
the syntax of an RGB triplet.
Available In
- button
- check
- field
- label
- line
- list
- popup
- radio
- tablet
- page global characteristics
- form global characteristics
Examples
This sample sets the background color to a chocolate brown.
fontcolor = ["210", "105", "30"];
Usage Notes
1) Default: ["0", "0", "0"]; (black)
-------
5.11 fontinfo
The fontinfo option defines the font name, point size, and
font characteristics for the text portion of an item.
Note: The font selected for an item influences the item's size.
Syntax
fontinfo = [<font name>, <point size>, <weight>, <effects>, <form>];
Note: <weight>, <effects> and <form> are optional.
Expression Setting Description
<font name> string the name of the font
<point size> short int the size of the font
<weight> "plain" use a plain face
"bold" use a bold face
Universal Forms Description Language [page 79]
<effects> "underline" underline the text
<form> "italic" use the italic form
Available In
- box
- button
- check
- field
- label
- line
- list
- popup
- radio
- spacer
- tablet
- page global characteristics
- form global characteristics
Example
This sample sets the font information to Times 14, bold italic.
fontinfo = ["Times", "14", "bold", "italic"];
Usage Notes
1) Defaults:
- font name: Helvetica
- point size: 8
- weight: plain
- effects: not underlined
- form: not italics
2) If any of the fontinfo settings are invalid, then the defaults
will be used.
3) The size option calculates item size using the font's average
character width. Therefore, choice of font affects item width.
4) The UFDL supports the following fonts and font sizes:
Fonts: Courier, Times, Symbol, Helvetica, and Palatino
Sizes: 8, 9, 10, 11, 12, 14, 16, 18, 24, 36, 48
5.12 format
The format option allows you to specify edit checks and formatting
options for field items.
Syntax
format = [<data type>, <format flag>, <check flag>];
Notes:
Universal Forms Description Language [page 80]
i) Multiple flags are valid.
ii) <data type> is mandatory and must appear first; the flags
are optional and can appear in any order.
Expression Setting Description
<data type> (see below) the type of data the field should
contain
<format flag> (see below) the type of formatting applied to the
user's input
<check flag> (see below) the type of edit check performed on
the formatted input
Available In
- combobox
- field
- label
- list
- popup
Data Types
The UFDL supports the following data types:
Data Type Description Format Defaults To:
string free form character data up to Any character
32K long
integer a positive or negative whole number Any whole number
in the range of -2,147,483,648 to +2,
147,483,647
float a positive or negative floating point Any decimal number
decimal number in the range of 1.7 *
10--308 to 1.7 * 10308
dollar a fixed point decimal number with a Any number.
scale of 2 and a range equal to the Automatically adds
range of a float .00 to end, if
decimal value
specified
date a date including day-of-month, month, This format:
and year 3 Mar 96
day_of_week the name or number of a day of the This format: Thu
week
month the name or number of a month This format: Mar
Universal Forms Description Language [page 81]
day_of_month the number of a day of the month Number format.
year a numeric year designation This format:
1996 | 2000 B.C.
time a time value containing hours This format:
and minutes from the 12 hour 11:23 P.M.
or the 24 hour clock
You can specify any number of format flags in a format line. To see
which format flags apply to each data type, see the cross reference
table at the end of this section.
The available format flags are:
Format Flag Description
comma_delimit Delimit the thousands by commas.
space_delimit Delimit the thousands by spaces.
bracket_negative Indicate negative values by surrounding
the value with parentheses, that is ( ).
add_ds Add a dollar sign to the start of the
value (dollar fields only).
upper_case Convert alphabetic characters to upper case.
lower_case Convert alphabetic characters to lower case.
short Display dates and times using the following
formats:
- day_of_week - numeric value in range
1 - 7 where 1 represents Sunday
- day_of_month - numeric value in range
1 - 31
- month - numeric value in range 1 to 12
- year - apostrophe followed by last two
digits in year ('98), 'before Christ'
era designator is B.C. ('98 B.C.)
- date - year as four digits, month as two
digits, and day-of-month as two digits,
organized in YMD order; no punctuation
(1998-04-29)
- time - 24 hour clock (as in 23:30)
long Display dates and times using the following
formats:
- day_of_week - name in full as in Monday
- day_of_month - two digits plus suffix as
in 1st
- month - name in full as in January
- year - four-digit numeric format,
'before Christ' era designator is B.C.
Universal Forms Description Language [page 82]
(2000 B.C.)
- date - long year, long month, and long
day-of-month formats organized in DMY
order; no punctuation (29th April 1998)
- time - 12 hour clock with the time of
day suffix (P.M.) for afternoon hours
(as in 11:30 P.M.)
numeric Display dates and times using numeric values
and, possibly, the minus sign:
- day_of_week - 2 digits in range 01 - 07
where 01 represents Sunday
- day_of_month - 2 digits in range 01 - 31
- month - 2 digits in range 01 - 12
- year - 4 digits; 'before Christ' era
designator is minus sign as in -1995
- date - month and day-of-month formats
above,
- year format is 4 digits
- 'before Christ' era designator is minus
sign
- organized in YMD order; no
punctuation
- Examples: 19980429, -19980429
- time - 24 hour clock (as in 23:30)
Check Flag
You can specify any number of edit checks in a format line. The edit
checks you specify and any edit checks implied by the data type will
be performed. To see which edit checks apply to each data type, see
the cross reference table at the end of this section.
Important: The UFDL specifies that fields be formatted before
an edit check is performed. For example, if the
field's data type is dollar and you specify the
add_ds and comma_delimit format options, then the
input 23000 becomes $23,000.00 before edit checks
are applied. This can affect length and template checks.
In this example, the length before formatting was five
but it became 10 before edit checking.
The available check flags are:
Check Flag Description
optional Input from the user is not mandatory.
mandatory Input from the user is mandatory.
case_insensitive Apply edit checks without regard to the case
in which the user enters the data.
range=["low","high"] The field's value must be in the range
Universal Forms Description Language [page 83]
specified. The range can be alphabetic,
numeric, days of the week, days of the month,
or months.
Ranges cannot vary from high to low. For
example, 10 to one, the year 2000 to 1900,
etc. are invalid.
length=["min","max"] Restrict the length of the formatted input
data to a minimum of "min" bytes and a
maximum of "max" bytes.
template=["a","b",...] This is a list of formats permitted for the
field. There is no restriction on the number
of formats. Field contents must match one of
the formats in the list. You may use any of
the following wild card characters:
- ? - represents any one (1) character?
- * - represents any number of characters
- # - represents any one (1) numeric
character
- % - represents any number of numeric
characters
- @ - represents any one (1) alphabetic
character
- ! - represents any number of alphabetic
characters
message="help" Sets the error message that is displayed if
the user input fails the type checking. The
default message is, "This entry is invalid.
Please try again."
Example
This sample specifies a field containing integer data with a range
of values from 10 to 1,000 inclusive, and formatted with commas
separating the thousands.
format = ["integer", "comma_delimit", range=["10", "1000"]];
Cross Reference of Data Types, Format Flags, and Check Flags
Data Type Applicable Format Flags Applicable Check Flags
string lower_case, upper_case case_insensitive,
length, range, template
integer bracket_negative, length, range, template
comma_delimit,
space_delimit
float bracket_negative, length, range, template
comma_delimit,
space_delimit
Universal Forms Description Language [page 84]
dollar add_ds, bracket_negative, length, range, template
comma_delimit,
space_delimit
date long, short, numeric case_insensitive, length
year range, template
month
day_of_month
day_of_week
time
Usage Notes
1) If a format flag conflicts with the data type, the format
flag will be ignored.
2) All edit checks specified will be applied to the input data.
This may result in a field the user cannot change. For
example, the combination of data type integer and check
flag template="a*" creates such a situation. Data cannot be
both an integer and begin with a letter.
3) Default Formatting
- Case remains unchanged.
- Numeric value format contains no thousands delimiter.
This permits easy conversion of ASCII to integer format.
- Dollar value format uses two decimal places and no dollar
sign.
- Zero is always positive.
- Day-of-week and month format is the abbreviated name
with no punctuation. For example, the 2nd day of the week
is always Mon; the first month is always Jan.
- The year format is long.
- The day_of_month is short.
- The date format uses the default day-of-month, month,
and year formats organized in DMY order as in 25 Dec 1995.
The 'before Christ' era designator is B.C.
- The time format defaults to short if the input is between
0:00 and 12:59, and to long otherwise.
4) Default Edit Checks
- All checking is case sensitive.
- The default edit checks combine the requirements of the
data type with any formatting requirements (default or
specific).
- If neither optional nor mandatory are specified, the rules
that are specified will determine whether the user must
enter information.
5) When applying a format to a combobox, list, or popup, the
formatting will be applied to the value of each cell linked to
the item. Those cells that do not pass the check will be flagged
Universal Forms Description Language [page 85]
or filtered. If a cell passes the checks, its value will be
replaced with a formatted value before the item is displayed.
The label option for these cells will remain unaffected.
6) When applying a format to a combobox, list, or popup, a cell
with an empty value will fail all format checks but will still
be selectable, even if input is mandatory. This allows users to
erase their previous choice (which will also reset all formulas
based on that choice). However, users will still need to select
a valid cell before they can submit the form.
7) If any two comboboxes, lists, or popups use the same set of
cells, they must apply the same formatting.
5.13 group
The group option provides a method of grouping items together.
Items with the same group reference are considered members of the
same group. Examples of grouped items are radio buttons and cells.
Syntax
group = <group reference>;
where <group reference> is one of:
- <group name> for groups on the current page
- <page tag>.<group name> for groups on other pages
Expression Setting Description
<group reference> string identifies the group
Available In
- cell
- combobox
- list
- popup
- radio
Example
This sample associates the item with the group coverage_type.
group = "coverage_type";
Usage Notes
1) Default: none
2) List and popup items are populated with cells that have
the same group reference as the item. It is possible to
have several list and popup items with the same group
reference. In this way, the same group of cells can populate
more than one list or popup.
3) All radio items having the same group reference will form
a mutually exclusive group.
Universal Forms Description Language [page 86]
5.14 help
The help option points to the help message for the item. The item
reference identifies the help item containing the help message.
There can be many items pointing to the same help message.
Syntax
help = <item reference>;
Expression Setting Description
<item reference> string identifies the help item
Available In
- button
- check
- field
- label
- list
- popup
- radio
- tablet
Example
This sample points to the help item general_help defined on the page
called page_1.
help = "page_1.general_help";
5.15 image
The image option associates an image with an item. The item
reference identifies the data item containing the image. This image
replaces any text label if the viewer is able to display images.
Syntax
image = <item reference>;
Expression Setting Description
<item reference> string Identifies the data item
Available In
- button
- label
- tablet
Example
Universal Forms Description Language [page 87]
This sample points to the data item company_logo defined on the page
called page_lst.
image = "page_lst.company_logo";
Usage Notes
1) Default: none
2) Use this option to associate images with button and label items.
5.16 itemlocation
The itemlocation option serves three purposes:
- It specifies the location of an item in the page layout.
- If you use the extent setting, it will set the size of
an item's bounding box.
- If you are using the relational positioning scheme, it may
dynamically alter the size of an item.
Each specification in the itemlocation option defines one aspect of
an item's location or size.
There are two different schemes you can use to position items on the
page: an absolute positioning scheme and a relational positioning
scheme. The absolute positioning scheme anchors the top left corner
of an item to a particular pixel on the displayed page, whereas the
relational positioning scheme places items on the page in relation
to one another. Once you understand the two schemes you can combine
them to gain the advantages of both schemes.
For more information on the two schemes, see 'Absolute Positioning
Scheme' and 'Relational Positioning Scheme', below.
Note: You can combine the two methods of positioning, so that
some items are positioned absolutely, and other items
are positioned in relation to those absolute items.
Syntax:
itemlocation = [[<specification1>], ... [<specificationn>]];
where:
(absolute positioning and extent modifier)
- <specification> is defined as: <modifier>,<x-coordinate>,
<y-coordinate> (relational positioning)
- <specification> is defined as: <modifier>, <item tag1>,
<item tag2>
Notes:
i) There is no restriction on the number of specifications.
ii) x-coordinate and y-coordinate may be negative only when
the modifier is offset.
iii) <item tag2> is valid only with the modifiers
alignhorizbetween and alignvertbetween.
Universal Forms Description Language [page 88]
Expression Setting Description
<modifier> (see below) the type of modification to apply
to the item's location or size
<x-coordinate> short - the horizontal distance in pixels
from the form's top left corner
(must be (with the modifier absolute); or
positive if - the horizontal distance in pixels
modifier is from the item's top left corner in
absolute its original position to its new
offset position (with the modifier
offset)
<y-coordinate> short - the vertical distance in pixels
from the form's top left corner
(must be (with the modifier absolute); or
positive if - the vertical distance in pixels
modifier is from the item's top left corner
absolute) in its original position and to
its new offset position (with the
modifier offset)
<item tag> string identifies the reference point
item
Modifiers
There are four types of modifiers:
- position modifiers - used to position an item
- alignment modifiers - used to align one edge of an
item (relational positioning only)
- expansion modifiers - used to alter an item's size
(relational positioning only)
- the extent modifier - used to set a pixel based size
for an item (both relational and absolute positioning)
Position Modifiers
For the Absolute Positioning Scheme:
Modifier Description
absolute Place top left corner of item on the pixel
noted in the x-coordinate and y-coordinate
settings.
offset Place item so that it is offset from its original
location by the measurement specified in the
x-coordinate and y-coordinate settings.
The extent modifier, listed later in this section, can also be used
with absolute positioning.
For the Relational Positioning Scheme:
Universal Forms Description Language [page 89]
Note: A specification containing the within modifier must be
the first specification in the list.
Modifier Description
above Place item a small distance above reference
point item; align left edges.
after Place item a small distance after reference
point item; align top edges.
before Place item a small distance before reference
point item; align top edges.
below Place item a small distance below reference
point item; align left edges.
within Assign item to the toolbar.
Alignment Modifiers (Relational Positioning only)
Note: The modifiers alignvertbetween and alignhorizbetween
require two reference items.
Modifier Description
alignb2b Align bottom edge of item with bottom edge
of reference point item.
alignb2c Align bottom edge of item with vertical center
of reference point item.
alignb2t Align bottom edge of item with top edge
of reference point item.
alignc2b Align vertical center of item with bottom edge
of reference point item.
alignc2l Align horizontal center of item with left edge
of reference point item.
alignc2r Align horizontal center of item with right
edge of reference point item.
alignc2t Align vertical center of item with top edge of
reference point item.
alignhorizbetween Align horizontal center of item between right
edge of first reference point item and left
edge of second reference point item.
alignhorizc2c Align horizontal center of item with
horizontal center of reference point item;
center below.
Universal Forms Description Language [page 90]
alignl2c Align left edge of item with horizontal center
of reference point item.
alignl2l Align left edge of item with left edge of
reference point item.
alignl2r Align left edge of item with right edge
of reference point item.
alignr2c Align right edge of item with horizontal
center of reference point item.
alignr2l Align right edge of item with left edge
of reference point item.
alignr2r Align right edge of item with right edge
of reference point item.
alignt2b Align top edge of item with bottom edge
of reference point item.
alignt2c Align top edge of item with vertical center
of reference point item.
alignt2t Align top edge of item with top edge of
reference point item.
alignvertbetween Align vertical center of item between bottom
edge of first reference point item and top
edge of second reference point item.
alignvertc2c Align vertical center of item with vertical
center of reference point item.
Expansion Modifiers (Relational Positioning only)
Modifier Description
expandb2c Hold top edge of item constant and expand
bottom edge to align with vertical center
of reference point item.
expandb2t Hold top edge of item constant and expand
bottom edge to align with top edge of
reference point item.
expandl2c Hold right edge of item constant and expand
left edge to align with horizontal center of
reference point item.
expandl2l Hold right edge of item constant and expand
left edge to align with left edge of reference
point item.
Universal Forms Description Language [page 91]
expandl2r Hold right edge of item constant and expand
left edge to align with right edge of
reference point item.
expandr2c Hold left edge of item constant and expand
right edge to align with horizontal center of
reference point item.
expandr2l Hold left edge of item constant and expand
right edge to align with left edge of
reference point item.
expandr2r Hold left edge of item constant and expand
right edge to align with right edge of
reference point item.
expandt2b Hold bottom edge of item constant and expand
top edge to align with bottom edge of
reference point item.
expandt2c Hold bottom edge of item constant and expand
top edge to align with vertical center of
reference point item.
expandt2t Hold bottom edge of item constant and expand
top edge to align with top edge of reference
point item.
The Extent Modifier (Relational and Absolute Positioning)
Modifier Description
extent Hold the top left corner of the item in place,
and size the item so that it is as many pixels
wide as the x coordinate, and as many pixels
tall as the y coordinate.
Available In
- box
- button
- check
- field
- label
- line
- list
- popup
- radio
- spacer
- tablet
Absolute Positioning Scheme
This scheme anchors an item to a particular coordinate on the
visible page. The coordinate is a measurement in pixels of the
Universal Forms Description Language [page 92]
distance between the top left corner of the form and the item's
top left corner.
The itemlocation line describing the label in the picture above
would look like this:
itemlocation = [["absolute", "60", "60"]];
The absolute positioning scheme also allows you to offset an item
from its original position, by a particular number of pixels. This
is a quick way to create an indented layout on your form.
It is valid to offset an item in any of these four directions:
right, left, up, down. Since the offset is measured by a pixel grid
and is represented with x and y coordinates, the directions left and
up are measured as negative distances. For example, to outdent the
Last Name field in the above diagram, so that its left edge is
further left than the label's, the x measurement would be negative,
as in -15.
You can offset an item from either:
- Its original absolute position. For example,
itemlocation = [["absolute", "60", "100"],
["offset", "15", "20"]];
- Its original relational position. For example,
itemlocation = [["below", "persInfo_label"],
["offset", "15", "20"]];
Caution
An absolute positioning scheme is not a cross-platform solution-nor
even a solution guaranteed to make forms appear the same under
different video cards or in both small font and large font modes.
The sizes of many UFDL form items are measured in characters. For
example, a field that is 60 x 1 in size, is 60 characters long and 1
character high. Because different platforms and video cards use
differently sized fonts, even for the so-called cross-platform
fonts, an item's actual size (in pixels) may change from one
platform to another as the font it is measured in changes size. If
you rely on spacing items on your form using absolute positioning,
which fastens an item to a particular pixel, some items may appear
overlapped on some platforms.
To ensure that your forms appear the same on any platform, and
under any video card or font mode, use relational positioning.
Relational Positioning Scheme
Relational positioning allows you to place an item relative to the
location of another item. It also allows you to specify an item's
size relative to the size and location of other items. The other
Universal Forms Description Language [page 93]
items (called reference point items) must be defined before they can
be used in an itemlocation statement.
When you use the relational positioning scheme, the first external
item you place on the form appears in the top left corner. It cannot
be placed in relation to any other item, since no other items exist.
All subsequent items can be placed in relation to items that appear
before them in the form's description. If you do not specify any
relational position for an item, it will appear below the previous
item, with its left edge against the page's left edge.
Itemlocation can only reference items on the same page as the item
being defined. If the item being defined is in a toolbar, the
referenced items must be in the same toolbar.
The Extent Modifier
The extent modifier allows you to set an absolute size for an item
in pixels. When you specify an extent, the item's top left corner
will stay where it is, and the item will be resized so that it is as
many pixels wide as the x value and as many pixels in height as the
y value.
Note: Itemlocation uses the bounding boxes of the defined and
referenced items to determine location and size.
Examples
Example 1 - Absolute Positioning
This sample places a label on the page so that its top left corner
is 20 pixels in from the page's left edge, and 30 pixels down from
the top of the page.
persInfo_label = new label
{
value = "Personal Information";
itemlocation = [["absolute", "20", "30"]];
}
Example 2 - Offsetting an Item
These samples show two ways in which to offset a field below the
label in example one. The first sample shows how to do so using only
the absolute positioning scheme. The second sample shows how to do
so using both relational and absolute positioning schemes.
lastName_field = new field
{
label = "Last Name";
itemlocation = [["absolute", "20", "100"],
["offset", "10", "10"]];
}
Universal Forms Description Language [page 94]
lastName_field = new field
{
label = "Last Name";
itemlocation = [["below", "persInfo_label"],
["offset", "10", "10"]];
}
Note that the item is offset from its original position, not from
other items. It's not a good idea to offset items using strictly
absolute positioning (sample one). Use relational positioning if
possible (sample two). For more information on the dangers of
absolute positioning, see 5.16 itemlocation;Caution.
Example 3 - Relational Positioning
Sample 3.1
This sample aligns the vertical center of an item between the bottom
edge of the item label_one and the top edge of the item label_two.
itemlocation = [["alignvertbetween", "label_one", "label_two"]];
Sample 3.2
This sample aligns the item's left edge with the center of item
the_firm and expands the right edge to align with the right edge of
the same reference item (the_firm).
itemlocation = [["alignl2c", "the_firm"], ["expandr2r",
"the_firm"]];
Sample 3.3
This sample assigns an item to the toolbar main_toolbar and
positions it under the company logo company_logo.
itemlocation = [["within", "main_toolbar"], ["below",
"company_logo"]];
Example 4 - Extent
Sample 4.1
This sample shows an extent setting on a field that has been placed
using absolute positioning. The field is first placed at an x-y
coordinate of 10, 10. It is then sized to be 300 pixels wide and 30
pixels high.
itemlocation = [["absolute", "10", "10"], ["extent", "300", "30"]];
Sample 4.2
The second sample shows an extent setting on a label that has been
placed using relational positioning. The label is first placed
Universal Forms Description Language [page 95]
below a field, and is then sized to be 100 pixels wide and 20 pixels
high.
itemlocation = [["below", "field_1"], ["extent", "100", "20"]];
Usage Notes
1) Default item location:
- in the body of the page
- under the previous item in the page definition
- aligned along the left margin of the page
Default bounding box size:
See 'Appendix B: Default Sizes'
2) Itemlocation overrides size. If the itemlocation affects
the size of the item and the size option has also been set
for the item, the itemlocation will determine the size.
3) An item's vertical center is halfway between the top and
bottom edges. The horizontal center is halfway between the
left and right edges.
4) See the following sections for more information on using
itemlocation:
- '2.4f Item Placement'
- '2.4e Item Size'
5) To offset an item by shifting it to the right or down the
page, specify the offset distance using positive integers.
To offset an item by shifting it to the left or up the page,
specify the offset distance using negative integers.
6) Use absolute positioning carefully. See 5.16 itemlocation;
Caution for more information.
5.17 justify
The justify option aligns lines of text within the space an item
occupies.
Syntax
justify = <alignment>;
Expression Setting Description
<alignment> "left" align each line's left edge along
the left margin
"right" align each line's right edge along
the right margin
"center" align the center of each line with
Universal Forms Description Language [page 96]
the center of the item
Available In
- button
- label
- popup
- tablet
Example
This sample aligns the text in the center of the item.
justify = "center";
If the item's text was:
The hare and the hound
Went off to the woods to play
It would display as follows:
The hare and the hound
Went off to the woods to play
Usage Notes
1) Default: varies depending on the item
- button and popup items: center
- label items: left
5.18 label
The label option specifies an external text label for an item. The
label appears above the item and aligned with its left margin. The
only exception is popup items, where the label appears inside the
item.
Syntax
label = <label text>;
Expression Setting Description
<label text> string the text of the label
Available In
- check
- field
- list
- popup
- radio
- spacer
- page global characteristics
- form global characteristics
Example
Universal Forms Description Language [page 97]
This sample defines a typical label.
label = "Student Registration Form";
Usage Notes
1) Default: none
2) Multiple line labels require line breaks imbedded in
the label text. Use the escape sequence '\n' to indicate
a line break. For example:
label = "This label spans\ntwo lines.";
5.19 labelbgcolor
The labelbgcolor option defines the background color for the label
specified in the label option.
Syntax
labelbgcolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See '5 UFDL Form
Options;Data Type Designators' for
the syntax of an RGB triplet.
Available In
- check
- field
- list
- radio
- page global characteristics
- form global characteristics
Examples
This sample sets the background color to red.
labelbgcolor = ["255", "0", "0"];
Usage Notes
1) Default: depends on the location of the item
- In the toolbar, it is the background color of the toolbar.
- Otherwise, it is the background color of the page.
5.20 labelbordercolor
The labelbordercolor option defines the color of the border around
Universal Forms Description Language [page 98]
the label specified in the label option.
Syntax
labelbordercolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See '5 UFDL Form
Options;Data Type Designators' for
the syntax of an RGB triplet.
Available In
- check
- field
- list
- radio
- page global characteristics
- form global characteristics
Examples
This sample sets the border color to blue.
labelbordercolor = ["0", "0", "255"];
Usage Notes
1) Default: ["0", "0", "0"]; (black)
5.21 labelborderwidth
The labelborderwidth option defines the width of the border around
the label specified in the label option. The unit of measurement is
pixels.
Syntax
labelborderwidth = <width>;
Expression Setting Description
<width> short int the width of the border
Available In
- check
- field
- list
- radio
- page global characteristics
- form global characteristics
Universal Forms Description Language [page 99]
Example
This sample sets the border width to 15 pixels.
labelborderwidth = "15";
Usage Notes
1) Default: zero pixels
5.22 labelfontcolor
The labelfontcolor option defines the font color for the label
specified in the label option.
Syntax
labelfontcolor = [<RGB triplet>];
Expression Setting Description
<RGB triplet> color the RGB triplet. See '5 UFDL Form
Options;Data Type Designators' for
the syntax of an RGB triplet.
Available In
- check
- field
- list
- radio
- page global characteristics
- form global characteristics
Example
This sample sets the font color to green.
labelfontcolor = ["0", "255", "0"];
Usage Notes
1) Default: ["0", "0", "0"]; (black)
5.23 labelfontinfo
The labelfontinfo option defines the font name, point size, and font
characteristics for the label specified in the label option.
Syntax
labelfontinfo = [<font name>, <point size>, <weight>,
Universal Forms Description Language [page 100]
<effects>, <form>];
Note: <weight>, <effects> and <form> are optional.
Expression Setting Description
<font name> string the name of the font
<point size> short int the size of the font
<weight> "plain" use plain face
"bold" use bold face
<effects> "underline" underline the text
<form> "italics" use the italic form
Available In
- check
- field
- list
- radio
- page global characteristics
- form global characteristics
Example
This sample sets the font information to Palatino 12,
plain (the default), underlined.
labelfontinfo = ["Palatino", "12", "underline"];
Usage Notes
1) See the section on fontinfo for the usage notes.
5.24 mimedata
The mimedata option contains the actual data associated with a data
item. It can be binary data or the contents of an enclosed file. The
data is encoded in base64 format.
Syntax
mimedata = <data>;
Expression Setting Description
<data> string the binary data or enclosed file contents
Available In
- data
Universal Forms Description Language [page 101]
Example
This sample assigns some encoded data to the mimedata option. Notice
the quotation marks surrounding each segment of the data.
mimedata =
"R0lGODdhYABPAPAAAP///wAAACwAAAAAYABPAAAC/4SPqcvtD02Y"
"Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrS2YzmTE+";
Usage Notes
1) Default: none
2) Base64 encoding transforms the data into a format that can be
processed easily by text editors, email applications, etc.
Converting data to base64 format ensures the resulting string
contains no characters requiring an escape sequence.
5.25 mimetype
The mimetype option defines the MIME type of the data stored in a
data item.
Syntax
mimetype = <MIME type>;
Expression Setting Description
<MIME type> string the MIME type of the data item
Available In
- data
Example
This sample sets the MIME type to indicate image data.
mimetype = "image/gif";
Usage Notes
1) Default: application/uwi_bin
2) Here are some examples of MIME types. For full information
on MIME types, read the MIME rfcs (1521, 1522 and 822).
You can find them on the World Wide Web.
MIME type Meaning
application/postscript Binary item
application/uwi_bin Binary item
application/uwi_form UFDL form item
Universal Forms Description Language [page 102]
application/uwi_nothing No data included
audio/basic Sound item
audio/wav Sound item
image/jpeg Image item
image/rast Image item
image/tiff Image item
image/png Image item
image/bmp Image item
text/plain ASCII text item
text/richtext Binary item
video/mpeg Video item
video/quicktime Video item
5.26 next
The next option identifies the item to receive focus when a user
tabs ahead from the current item. If the specified item is on
another page, the new page appears with the item in focus. Only
modifiable items can receive focus.
See section '2.4n Defining Tabbing and Paging' for more
information on tabbing.
Syntax
next = <item reference>;
Expression Setting Description
<item reference> string identifies the item to receive
focus next
Available In
- button
- check
- field
- list
- popup
- radio
- tablet
- page global characteristics
- form global characteristics
Universal Forms Description Language [page 103]
Example
This sample points to the item address_field. When users tab ahead
from the current item, the item identified as address_field will
receive focus.
next = "address_field";
Usage Notes
1) Default tabbing order: depends on the order in which page and
item definitions occur within the form definition. The sequence
is:
- first page to display: first page defined in the form
- first item to receive focus: first modifiable item defined
for the body of the first page
- subsequent items to receive focus: each modifiable item on
the page in the order you define them
When you tab past the last item on the page, the first modifiable
item in the page's toolbar receives focus. If there is no toolbar,
focus returns to the first item.
2) Placing the next option in form characteristics defines the
first page to appear, and the first item to receive focus when
the form opens. Placing next in page characteristics defines
the first item to receive focus when the page appears.
3) If the next option identifies form or page characteristics,
focus moves to the item defined to receive focus when the form
or page appears. The form characteristics reference is
global.global. The page characteristics reference is global
for the current page or <page tag>.global for another page.
5.27 printsettings
The printsettings option determines the settings that will be used
when the form is printed. You can allow the user to change these
defaults, or set the form so that it will always follow the
defaults.
Syntax
printsettings = [<page list>, <dialog settings>];
Notes:
- All settings are optional.
Expression Setting Description
<page list> (see below) the list of pages that should be
printed
<dialog settings> (see below) determines whether the print
Universal Forms Description Language [page 104]
dialog is shown, and which
settings should be used when
printing (for example,\paper
orientation and number of copies)
Available In
- action
- button
- cell
- page global characteristics
- form global characteristics
Page List
The page list uses the following syntax:
pages=["keep"|"omit", "<page tag 1>", "<page tag 2>", ...]
The settings for the page list work as follows:
Setting Description
keep The pages listed will be printed. Any
other pages will not.
omit The pages listed will not be printed.
Any other pages will.
<page tag> The list of page tags indicates which
pages should be either kept or omitted.
Dialog Settings
The dialog settings use the following syntax
dialog=[active="on"|"off", orientation="portrait"|"landscape",
copies="1"]
The settings work as follows:
Setting Description
active When "on", the print dialog will be
displayed before the form is printed,
allowing the user to change the settings.
When "off", the dialog will not be shown
and the form will be printed immediately.
orientation Determines whether the form will be printed
in "landscape" or "portrait" orientation.
copies Determines the number of copies that will
be printed.
Universal Forms Description Language [page 105]
printpages See below.
Example
This sample omits "page2" from printing, sets the form to print
in landscape orientation, and causes two copies of the form to
be printed. The user is able to change all of these settings.
printsettings=[pages=["omit", "page2"], dialog=["on",
orientation="landscape", copies="2"]];
Usage Notes
1) Default Page List: the page list will default to keeping
all pages in the form.
2) Default Dialog Settings: the dialog will default to being
"on", and will print one copy of all pages in the form in
a portrait orientation. By default, the user will be able
to change all of these settings.
5.28 saveformat
The saveformat option specifies what format a form should be saved
in. A UFDL form can be saved in UFDL format, compressed UFDL format,
or HTML format.
UFDL format saves the entire form definition, including the user
input. Compressed UFDL format saves the entire form description as
a compressed file using a gzip compression algorithm.
HTML format saves the form as a series of assignment statements for
each modifiable item, equating the item reference with the item's
value. The only items included in the save are custom items and the
following modifiable items: check, field, list, popup, radio.
Syntax
saveformat = <MIME type>;
Expression Setting Description
<MIME_type> "application/uwi_form" use UFDL format
"application/uwi_form; use compressed
content-encoding=\"gzip\"" UFDL format
"application/x-www-form- use HTML format
urlencoded"
Note: You cannot specify that HTML format files be compressed.
Available In
- button
Universal Forms Description Language [page 106]
- cell
- form global characteristics
Example
Example 1 - HTML format in a button
This example shows how to use saveformat in a save button.
save_button = new button
{
type = "save";
saveformat = "application/x-www-form-urlencoded";
}
When a user clicks this button, the form will be converted
to HTML format (see Usage Note 3 below) and saved to the
user's drive.
Example 2 - Compressed UFDL format in form global characteristics
This example shows how to use saveformat as a form global
characteristic and to specify that the saved form be compressed.
version = "3.2.0";
bgcolor = ["255", "255", "240"];
saveformat = "application/uwi_form; content-encoding = \"gzip\"";
page_1 = new page
{
Any time a user saves this form, it will be saved in compressed UFDL
format.
A saveformat setting as a form global characteristic applies to all
save actions for the form. You can override the global setting for
specific save actions by coding a different saveformat option into
the item that initiates the save action. For example,
version = "3.2.0";
bgcolor = ["255", "255", "240"];
saveformat = "application/uwi_form; content-encoding = \"gzip\"";
page_1 = new page
{
save_button = new button
{
type = "save";
value = "Save Form";
saveformat = "application/uwi_form";
}
When the user saves the form by clicking the Save Form button, it
will be saved as an uncompressed UFDL form.
Universal Forms Description Language [page 107]
Note that the quotation marks around gzip must be escaped.
Usage Notes
1) Default: UFDL format (not compressed)
2) You can include this option as a form global option
and in the definitions of items that trigger save actions.
These are button or cell items that have a type option
setting of save.
3) HTML Format by Item Type
The general syntax of a form saved in HTML format is:
<item reference>=<value>&< item reference>=<value>&...
Note: the ampersand separates form items.
The syntax of items saved in HTML format by type:
Item Type HTML Format
check <item tag>=<value option setting>
field <item tag>=<value option setting>
list <item tag>=
<value option setting of selected cell>
Note: <item reference> identifies the list.
popup <item tag>=
<value option setting of selected cell>
Note: <item reference> identifies the popup.
radio <group option setting>=
<item tag of selected radio>
<custom> <item tag>=<value option setting>
Substitutions and Omissions:
- Only modifiable items are saved as HTML data. You cannot
save a form in HTML format and expect to view it as a
form again. It is saved as a string of item tags and
their associated values.
- Spaces in the value are replaced by the plus sign (+).
'Two words' becomes 'Two+words'
- The membership operator in item and group references
is replaced by a minus sign.
'page_one.age_group' becomes 'page_one-age_group'
Universal Forms Description Language [page 108]
- Page tags are removed from item and group references
in single page forms.
- Check boxes and radio buttons with a value option
setting of off are omitted.
- Entries resulting in an empty string on the right hand
side of the assignment statement are omitted. This
occurs when the referenced option setting is empty or
the option definition is missing.
5.29 scrollhoriz
The scrollhoriz option defines horizontal scrolling options
for a field item.
Syntax
scrollhoriz = <option>;
Expression Setting Description
<option> "never" permit scrolling using the cursor
but display no horizontal scroll bar
"always" permit scrolling and display a horizontal
scroll bar
"wordwrap" wrap field contents from line to line,
inhibit scrolling and display no
horizontal scroll bar
Available In
- field
Example
This sample sets the horizontal scrolling option to permit scrolling
and to display the horizontal scroll bar.
scrollhoriz = "always";
Usage Notes
1) Default: never
2) The scroll bar displays along the field's bottom edge.
5.30 scrollvert
The scrollvert option defines vertical scrolling options for a
field item.
Universal Forms Description Language [page 109]
Syntax
scrollvert = <option>;
Expression Setting Description
<option> "never" permit scrolling using the cursor
but display no vertical scroll bar
"always" permit scrolling and display a
vertical scroll bar
"fixed" inhibit scrolling and display no
vertical scroll bars
Available In
- field
Example
This sample sets the vertical scrolling option to inhibit all
scrolling.
scrollvert = "fixed";
Usage Notes
1) Default: never
2) The scroll bar displays along the field's right edge.
5.31 size
The size option specifies an item's size. It does not include
external labels, borders or scroll bars. These are part of the
bounding box size which is calculated automatically. The size unit
of measurement is characters.
Examples of item size are the input area in a field item or the
height and width of the label in label and button items.
See '2.4e Item Size' for a discussion of item and bounding
box sizes.
Syntax
size = [<width>, <height>];
Expression Setting Description
<width> short int the horizontal dimension of the
item
Universal Forms Description Language [page 110]
<height> short int the vertical dimension of the item
Available In
- box
- button
- check
- field
- label
- line
- list
- popup
- radio
- spacer
- tablet
Example
This sample sets the item's size to 80 characters wide by five
characters high.
size = ["80", "5"];
Usage Notes
1) Defaults: See 'Appendix B: Default Sizes'
2) Size and Font:
The width may not always accommodate the number of
characters you specify. The calculation to determine
actual width is:
'average character width for the item's font' X <width>
This will only exactly match the number of characters the
item can display horizontally when the font is mono-spaced
(like Courier).
3) If either the height or the width is invalid, the default
item size will be used. A dimension of zero (0) is invalid
for all items except line.
4) The item and bounding box sizes can be changed by using
itemlocation with an expansion or extent modifier.
5.32 thickness
The thickness option specifies the thickness of a line. The unit of
measurement is pixels.
Syntax
thickness = <thickness>;
Universal Forms Description Language [page 111]
Expression Setting Description
<thickness> short int the thickness of the line
Available In
- line
Example
Example 1
This sample defines a horizontal line 40 characters long and
five pixels thick.
size = ["40", "0"];
thickness = "5";
Example 2
This sample defines a vertical line 20 characters long and 10
pixels thick.
size = ["0", "20"];
thickness = "10";
Usage Notes
1) Default: one pixel
2) Use size to define the dimension of a line in one direction
(height or width) and thickness to define the dimension in
the other direction. The dimension thickness defines must
be set to zero in size.
3) The line's thickness can be changed by using itemlocation
with an expansion modifier for the dimension that thickness
describes.
5.33 transmit
The transmit option specifies whether an item's definition should be
included in the form data submitted to a form processing
application. This option and the transmititems and transmitoptions
options determine whether form submission is partial or complete.
Transmit specifies the handling of a particular item, and is part of
that item's definition. Transmititems and transmitoptions specify
the handling of types of items and types of options, and are part of
a trigger item's definition. Transmit overrides the other two
options.
Syntax
transmit = <transmit flag>;
Universal Forms Description Language [page 112]
Expression Setting Description
<transmit flag> "all" include item definition regardless
of transmititems and transmitoptions
option settings in the trigger item
"filter" decision to include item definition
based on transmititems and
transmitoptions option settings in
the trigger item
"none" do not include item definition
Available In
- all items, including custom items
- page global characteristics
- form global characteristics
Example
This sample specifies that this item and all its options should be
included in any form submission regardless of the transmititems and
transmitoptions settings.
transmit = "all";
Usage Notes
1) Default: filter
2) Associate this option with any item in the form including
<custom> items.
3) If you include a transmit option of none in the page
characteristics, only the items from that page with a transmit
option of all or filter may be transmitted. The page
characteristics themselves will be transmitted.
4) If you include the transmit option with a setting none in the
form characteristics, only those pages or items with a transmit
option of all or filter may be transmitted. The form
characteristics themselves will be transmitted, along with the
characteristics for each page in the form.
5.34 transmitformat
The transmitformat option specifies the format of the form data
submitted to a processing application. A UFDL form can submit data
in UFDL format, compressed UFDL format, or in HTML format.
UFDL format is the entire form definition, including user input,
unless you use the options transmit, transmititems, and
transmitoptions to omit some items and options from the form
Universal Forms Description Language [page 113]
submission.
HTML format is just an assignment statement for each item equating
the item reference with the item's value. The only items included
are modifiable items, custom items, and items with a transmit option
setting of all.
If you specify that a UFDL format submission should be compressed,
it will be compressed using a gzip compression algorithm.
Note: Form and page global characteristics are sent only if the
format is UFDL.
Syntax
transmitformat = <MIME_type>;
Expression Setting Description
<MIME_type> "application/uwi_form" use UFDL format
"application/uwi_form; use compressed
content-encoding=\"gzip\"" UFDL format
"application/x-www-form use HTML form
-urlencoded" format
Note: You cannot specify that data in HTML form format be
compressed.
Available In
- action
- button
- cell
- form global characteristics
Examples
Example 1 - UFDL format
This example shows a button which, when clicked, will submit
the form in UFDL format.
send_button = new button
{
type = "done";
url = ["mailto:user@host.domain"];
transmitformat = "application/uwi_form";
}
When a user clicks the button, the entire form definition will
be submitted, unless other transmit options specify a partial\
submission.
Universal Forms Description Language [page 114]
Example 2 - Compressed UFDL format specified in form global
This example shows how to use the transmitformat option as a form
global option. Here, it specifies that data should be submitted in
compressed UFDL format.
version = "3.2.0";
bgcolor = ["255", "255", "240"];
transmitformat = "application/uwi_form; content-encoding=\"gzip\"";
page_1 = new page
{
...
When a submit or done action is activated in the form, the data will
be sent in compressed UFDL format. When transmitformat appears as a
form global characteristic, it applies to all submissions from the
form. You can override it for a particular submission if you place a
transmitformat setting in the item that initiates the submission.
Note that the quotation marks around gzip must be escaped.
Example 3 - HTML form format
This sample shows an automatic action that submits form data in
HTML form format.
status_action = new action
{
type = "submit";
url = ["http://www.host.domain/cgi-bin/recvStatus"];
transmitformat = "application/x-www-form-urlencoded";
delay = ["repeat", "180"];
}
Every 180 seconds, the form definition will be converted to HTML
form format as specified in Usage Note 4. Other transmit options
could override the choice of items to include in an HTML form
(see Usage Notes 5 and 6).
Usage Notes
1) Default: UFDL format (not compressed)
2) You can include this option as a form global option and in
the definitions of items that trigger form submissions.
These items have a type option setting of submit or done.
3) HTML Format by Item Type
The general syntax of a submitted HTML form is:
<item reference>=<value>&< item reference>=<value>&...
Note: the ampersand separates form items.
Universal Forms Description Language [page 115]
The syntax of an HTML form entry by item type:
Item Type HTML Format
check <item tag>=<value option setting>
field <item tag>=<value option setting>
list <item tag>=
<value option setting of selected cell>
Note: <item reference> identifies the list.
popup <item tag>=
<value option setting of selected cell>
Note: <item reference> identifies the popup.
radio <group option setting>=
<item tag of selected radio>
<custom> <item tag>=<value option setting>
all other items <item tag>=<value option setting>
Substitutions and Omissions:
- Spaces in the value are replaced by the plus sign (+).
'Two words' becomes 'Two+words'
- The membership operator in item and group references
is replaced by a minus sign.
'page_one.age_group' becomes 'page_one-age_group'
- Page tags are removed from item and group references
in single page forms.
- Check boxes and radio buttons with a value option setting
of off are omitted.
- Entries resulting in an empty string on the right hand side
of the assignment statement are omitted. This occurs when the
referenced option setting is empty or the option definition is
missing.
4) Partial Submissions
Just as you can specify partial submissions when transmitting
data in UFDL format, you can also specify partial submissions
when transmitting data in HTML format. Use the transmit and
transmititems options.
Use the transmitoptions option for HTML formatted submissions
with caution. If you omit the options used for HTML format,
then items requiring those options are omitted also.
Universal Forms Description Language [page 116]
For example, if the trigger item's definition included the
following pair of statements, the form submission would contain
only radio item entries (all other entries use a value option
setting).
transmitformat = "application/x-www-form-urlencoded";
transmitoptions = ["omit", "value"];
5) HTML Considerations
The functionality of UFDL forms differs somewhat from HTML
forms. Those differences are:
- Enclosures
HTML does not support enclosures. To submit enclosed form
data, use the UFDL format.
- Item tags
UFDL allows a smaller set of characters in item tags than
HTML does. UFDL item tags support the following characters:
a-z, A-Z, 0-9, and the underscore ( _ ).
- Check boxes
UFDL check boxes vary slightly from HTML check boxes. UFDL
check boxes are independent items; HTML check boxes are
grouped together using the same format as radio items. When
a UFDL form is submitted in HTML format, the submission will
contain an entry for each check box.
5.35 transmititems
This option lists the types of items to include in or omit from the
form data submitted to a form processing application. Include this
option in the definitions of items that trigger form submissions.
These trigger items have a type option setting of submit or done.
Only items with a transmit option setting of filter are affected by
transmititems. Filter is the default transmit option setting;
therefore, this includes items without a transmit option definition.
Syntax
transmititems = [<transmit flag>, <item type1>, ... <item typen>];
Note: The number of <item type> entries is optional.
Expression Setting Description
<transmit flag> "keep" include items with an item type from
the <item type> list; omit those not
in list
"omit" omit items with an item type from
the <item type> list; include those
not in list
Universal Forms Description Language [page 117]
<item type> string a type of item
Tip: Transmititems does not affect items with a transmit option
setting of all or none.
Available In
- action
- button
- cell
Example
This sample specifies that box, help, label, spacer, and toolbar
items should be omitted from the form data submitted to the form
processing application.
transmititems = ["omit", "box", "help", "spacer", "toolbar"];
Usage Notes
1) Default: keep all items
2) See section '5.33 transmit' for more information
on the syntax and meaning of this option.
3) The following tables demonstrate the relationship between
the transmit option and the transmititems option. Notice that
items without a transmit option are treated identically to
items with a transmit option setting of filter. This is because
filter is the default.
- Items included the <item type> list:
Transmit option Transmititems flag Transmititems
setting "keep" flag "omit"
all included included
filter included omitted
none omitted omitted
(not specified) included omitted
- Items not included the <item type> list:
Transmit option Transmititems flag Transmitiems
setting "keep" flag "omit"
all included included
filter omitted included
none omitted omitted
Universal Forms Description Language [page 118]
(not specified) omitted included
5.36 transmitoptions
This option lists which options to include in or omit from the form
data submitted to a form processing application. Include this option
in the definitions of items that trigger form submissions. These
trigger items have a type option setting of submit or done.
Only options meeting the following criteria are affected by
transmitoptions:
- The option definition occurs in an item already included in
the form submission.
- The option definition occurs in an item with a transmit
option setting of filter. Filter is the default transmit option
setting; therefore, this includes items without a transmit option
definition.
Note: The version option is always included in the submission
unless the format is HTML.
Syntax
transmitoptions = [<transmit flag>, <option identifier1>,
... <option identifiern>];
Note: The number of <option identifier> entries is optional.
Expression Setting Description
<transmit flag> "keep" include options with an option
type in the <option identifier>
list; omit those not in list
"omit" omit options with an option
identifier in the <option
identifier> list; include those
not in list <option identifier>
string a type of option
Tip: Transmitoptions does not affect options found in items with a
transmit option setting of all or none, or in items omitted by
the transmititems option.
Available In
- action
- button
- cell
Example
This sample specifies that only the active, mimedata, and value
options should be included in the form data submitted to the form
Universal Forms Description Language [page 119]
processing application.
transmitoptions = ["keep", "active", "mimedata", "value"];
Usage Notes
1) Default: keep
2) See the section '5.33 transmit' for more information on the
syntax and meaning of this option.
3) The following tables demonstrates the relationship between the
item status, and the transmit and transmitoptions options.
Notice that options in items without a transmit option are
treated identically to options in items with a transmit option
setting of filter. This is because filter is the default.
- For options occurring in omitted item definitions:
the options are omitted also.
- For options occurring in included item definitions and in the
<option identifier> list:
Transmit option Transmitoptions flag Transmitoptions
flag
setting "keep" "omit"
all included included
filter included omitted
none omitted omitted
(not specified) included omitted
- For options occurring in included item definitions but not in the
<option identifier> list:
Transmit option Transmitoptions flag Transmitoptions
flag
setting "keep" "omit"
all included included
filter omitted included
none omitted omitted
(not specified) omitted included
5.37 triggeritem
The triggeritem option identifies the item that triggered a form
submission. Items triggering form submissions have a type option
setting of submit or done.
When a user selects an item that triggers a form submission, the
Universal Forms Description Language [page 120]
triggeritem option is added to the form global characteristics and
assigned the item reference of the selected item.
Syntax
triggeritem = <item reference>;
Expression Setting Description
<item reference> string identifies the trigger item
Available In
- form global characteristics
Example
This sample indicates that the item triggering the request is on the
page called Page_one and has an item tag of submit_button.
triggeritem = "Page_one.submit_button";
5.38 type
The type option associates a task type with an item that can trigger
a task: action, button, or cell.
Syntax
type = <task type>;
Expression Setting Description
<task type> (see below) the task to perform
Task Types
The <task type> can be any of the following:
Task Type Description of Task Use With
link Perform all requests specified by the url action
options in the current item. See the section button
'url' for more details. cell
replace Perform a link followed by a cancel. action
button
cell
submit Initiate the form processing applications action
identified in the url options of the current button
item. cell
done Perform a submit followed by a cancel. action
button
cell
Universal Forms Description Language [page 121]
pagedone Move to the page specified in the url option. action
This closes the current page and replaces it button
with the new page. All fields containing error cell
checking on the current page must be correctly
filled out before it can be closed.
cancel Close the form; if any changes were made to the action
form since the last save or submit, then the button
user is informed that the form has changed and is cell
allowed to choose whether the cancellation should
proceed. Note that the value options of many items,
as well as the contents of data items, can change,
in response to an enclose or remove action.
save Save the form in a file specified by the user. action
button
cell
select With cell items: flag the cell as selected when button
a user chooses the cell. This means the item cell
reference of the cell is copied to the value
option of the parent list or popup.
With button items containing images: store
coordinates of the mouse click position in the
image into the coordinates option.
enclose Allows the user to place one or more files into button
one or more of the datagroups defined for the cell
form. The files will be encoded using base64
encoding format.
extract Allows a user to copy the contents of an button
enclosed file into a file on the local disk. cell
remove Allows the user to remove an item from a action
datagroup; the underlying data item will button
only be deleted if it belongs to no other cell
datagroups.
display Display an enclosed file. Your web browser action
will choose the appropriate viewer according button
to the file's MIME type. cell
print Print the form on a local printer. action
button
cell
Available In
- action
- button
- cell
Universal Forms Description Language [page 122]
Example
This sample specifies that this item saves the form to a local file.
type = "save";
Usage Notes
1) Default: link
5.39 url
The url option identifies an object to access. Items containing this
option must have a type option setting of link, replace, submit,
done, or pagedone.
The object identified can be any of the following:
- File - used with a type option setting of link or replace
The file identified is downloaded, and either displayed or saved.
Examples of such files are images, word processing documents, and
UFDL forms.
- Application - used with a type option setting of submit or done
The application identified is initiated. A form processing
application is an example of such an application.
- Item - used with a type option setting of pagedone
The item identified, on the page identified, receives focus.
The item must be on another page.
- Form or Page Characteristics - used with a type option setting
of pagedone. The focus moves to the item defined to receive focus
when the form or page appears. The form characteristics reference
is global.global. The page characteristics reference is
<page tag>.global for another page.
Syntax
url = [<the URL1>, <the URL2>, ... <the URLn>];
where <the URL> is one of:
- a URL with the format <scheme://host.domain[:port]/path/filename>
for files and applications
- #<item reference> for the next item in the form to receive focus
Notes:
i) <the URL> can occur 1-n times.
ii) <item reference> can be a form or page characteristics reference.
Expression Setting Description
<the URL> string identifies the object to link
Available In
- action
Universal Forms Description Language [page 123]
- button
- cell
Example
This sample identifies a form processing application.
url = ["http://www.host.domain/cgi-bin/recv_status"];
This sample identifies a page to display and an item on it to direct
the focus to.
url = ["#page_2.expense_field"];
Usage Notes
1) Default: none
2) When a form communicates with a server, the information sent may
be URL-encoded. This means all non alpha-numeric characters are
replaced by a character triplet consisting of the "" character
followed by two hexadecimal digits that form the hexadecimal
value of the original character. The hexadecimal digits are
"0123456789ABCDEF". For example,
Character ASCII Number URL-encoded triplet
<space> 32 20
\r 13 0D
Applications receiving form data must check the content type of the
incoming data to see whether it is url-encoded.
5.40 value
The value option reflects the contents of an item. Visually, this
can take several forms, depending on the item to which it applies.
For example, the value option in label items contains the label
text; the value option in radio items contains the status indicator;
and the value option in list items contains the identity of the most
recently selected cell (if it was a select cell).
An item's contents will be stored in the form whenever a user saves
the form or submits it for processing. This is true even for
inactive items and items using the default value option setting
(in this case, a value option containing the default setting is
added to the item's definition).
Syntax
value = <setting>;
Expression Setting Description
<setting> string the item's contents
Universal Forms Description Language [page 124]
Available In
- button
- cell
- check
- field
- help
- label
- list
- popup
- radio
- tablet
Example
This sample identifies the text of a label item.
value = "My Form Title";
Usage Notes
1) Default: varies by item. See the documentation for each item.
2) Multiple line values require line breaks imbedded in the value
text. Use the escape sequence '\n' to indicate a line break.
For example:
value = "This value spans\ntwo lines.";
5.41 version
The version option specifies the Universal Forms Description
Language version used to code the form definition.
Note: This option must be the first statement in the form. It is
invalid in any other location.
Syntax
version = <version>;
Expression Setting Description
<version> string the UFDL version number.
Note: The version number must be coded as a quoted string. Other
expression formats are invalid in this statement.
Available In
- form global characteristics (mandatory)
Example
Universal Forms Description Language [page 125]
This sample indicates the language in this form definition conforms
to the UFDL version 3.2.0 specification.
version = "3.2.0";
Usage Notes
1) Important: Do not increase the version number of old forms
unless they have been modified to conform to the new version.
2) The format of a version number is m.n.r where:
i) m is the major version number
ii) n is the minor version number
iii) r is the maintenance release number
For example, the version number for this release of the
Universal Forms Description Language is 3.2.0.
5.42 <custom option>
Custom options allow form designers to add application specific
information to the form definition. This is useful when submitting
forms to applications requiring non-UFDL information. An example of
non-UFDL information might be an SQL query statement.
Syntax
<custom> = [<expression1>, ... <expressionn>];
Note: <expression> can occur 1-n times.
Expression Setting Description
<expression> string an expression that assigns
a value to the option
Example
This sample shows a custom option containing an SQL query.
sql_query = ["SELECT NAME FROM EMPLOYEE WHERE ID = "];
This statement could be included in the definition of an item that
triggers a form submission. The form processing application might
then complete the statement with a value option setting from another
item, and use the statement results to populate a response form.
Usage Notes
1) The naming conventions for a custom option are as follows:
- It must begin with an alphabetic character.
- It can contain any of the characters A-Z, a-z, 0-9, $ and
underscore.
- It must contain an underscore.
Universal Forms Description Language [page 126]
6. UFDL Form Viewer Directive
The UFDL contains the following viewer directive statement:
- the #include statement for including external files
The syntax of a viewer directive statement is as follows:
#<directive> "<value>"
Do not terminate viewer directive statements with a semicolon.
See section '5 UFDL Form Options' for syntax
notation conventions.
6.1 #include
The #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 include file before the
form appears.
Syntax
#include "<filename>"
Value Setting Description
<filename> string name of the include file
Example
This is an example of using an include file to add image data to
a form.
Here is the original form definition:
?
// Create a label to display the image.
LOGO_IMAGE = new label
{
image = "LOGO_DATA";
}
//
// Now include the image in the form.
#include "logo.frm"
?
This is the external file:
// Don't permit the image to be transmitted with a submitted form.
LOGO_DATA = new data
{
transmit = "none";
mimedata = "<image data>";
Universal Forms Description Language [page 127]
}
The form after resolution of the include:
?
// Create a label to display the image.
LOGO_IMAGE = new label
{
image = "LOGO_DATA";
}
//
// Now include the image in the form.
// Don't permit the image to be transmitted with a submitted form.
LOGO_DATA = new data
{
transmit = "none";
mimedata = "<image data>";
}
?
Usage Notes
1) You can code a #include statement anywhere in a form definition
except imbedded in another statement. You can also nest #include
statements.
2) The include file must reside in a secure include directory
accessible to the form viewer application.
3) Use include files to reduce form file size, and ensure
standardization of form definitions. Smaller files occupy less
space on the server and download more quickly.
Appendix A: Quick Reference Tables
A.1 Table of Items and Form and Page Characteristics
Item Available Options
action active; datagroup; delay; transmit; transmitformat;
transmititems; transmitoptions; type; url
box bgcolor; bordercolor; borderwidth; fontinfo;
itemlocation; size; transmit
button active; bgcolor; bordercolor; borderwidth;
coordinates; datagroup; editstate; fontcolor;
fontinfo; help; image; itemlocation; justify;
next; saveformat; size; transmit; transmitformat;
transmititems; transmitoptions; type; url; value
cell active; datagroup; editstate; group; saveformat;
transmit; transmitformat; transmititems;
transmitoptions; type; url; value
Universal Forms Description Language [page 128]
check active; bgcolor; bordercolor; editstate; fontcolor;
fontinfo; help; itemlocation; label; labelbgcolor;
labelbordercolor; labelborderwidth; labelfontcolor;
labelfontinfo; next; size; transmit; value
combobox active; bgcolor; bordercolor; borderwidth;
editstate; fontcolor; fontinfo; format; group;
help; itemlocation; label; labelbgcolor;
labelbordercolor; labelborderwidth; labelfontcolor;
labelfontinfo; next; size; transmit; value
data datagroup; filename; mimedata; mimetype; transmit
field active; bgcolor; bordercolor; borderwidth;
editstate; fontcolor; fontinfo; format; help;
itemlocation; label; labelbgcolor; labelbordercolor;
labelborderwidth; labelfontcolor; labelfontinfo;
next; scrollhoriz; scrollvert; size; transmit;
value
help active; transmit; value
include filename; transmit
label active; bgcolor; bordercolor; borderwidth;
fontcolor; fontinfo; help; image; itemlocation;
justify; size; transmit; value
line fontcolor; fontinfo; itemlocation; size; thickness;
transmit
list active; bgcolor; bordercolor; borderwidth;
editstate; fontcolor; fontinfo; group; help;
itemlocation; label; labelbgcolor; labelbordercolor;
labelborderwidth; labelfontcolor; labelfontinfo;
next; size; transmit; value
popup active; bgcolor; bordercolor; borderwidth;
editstate; fontcolor; fontinfo; group; help;
itemlocation; justify; label; next; size; transmit;
value
radio active; bgcolor; bordercolor; editstate; fontcolor;
fontinfo; group; help; itemlocation; label;
labelbgcolor; labelbordercolor; labelborderwidth;
labelfontcolor; labelfontinfo; next; size; transmit;
value
spacer fontinfo; itemlocation; label; size; transmit
tablet active; bgcolor; bordercolor; borderwidth;
fontcolor; help; image; itemlocation; justify;
next; size; transmit; value
toolbar bgcolor; transmit
Universal Forms Description Language [page 129]
page char. bgcolor; bordercolor; borderwidth; fontcolor;
fontinfo; label; next; transmit
form char. bgcolor; bordercolor; borderwidth; fontcolor;
fontinfo; label; next; saveformat; transmit;
transmitformat; triggeritem; version
A.2 Table of Options
Option Details
active Syntax: active = <"on" | "off">;
Default: on
Items: action; button; cell; check; combobox;
field; help; label; list; popup; radio;
tablet. To prevent user input in a field,
use the editstate "readonly".
bgcolor Syntax: bgcolor = ["<color name>"];
bgcolor = ["<R value>","<G value>",
"<B value>"];
Default: for button - gray
for check, field, list, popup, radio
- "white"
all other items - the background
color of the form
Items: box; button; check; combobox; field;
label; list; popup; radio; tablet;
toolbar; page characteristics; form
characteristics
bordercolor Syntax: bordercolor = ["<color name>"];
bordercolor = ["<R value>","<G value>",
"<B value>"];
Default: the bordercolor set in the global
characteristics, or "black" if no
characteristics set
Items: box; button; check; combobox; field;
label; list; popup; radio; tablet; page
characteristics; form characteristics
borderwidth Syntax: borderwidth = "<width>";
Default: for label - 0
for all other items - the borderwidth
set in characteristics, or 1 if no
characteristics set
Items: box; button; combobox; field; label;
list; popup; tablet; page
characteristics; form characteristics
coordinates Syntax: coordinates = ["<X_coordinate>",
"<Y_coordinate>"];
Default: none
Items: button
Universal Forms Description Language [page 130]
datagroup Syntax: datagroup = ["<datagroup_reference>",
"<datagroup reference>"...];
Default: none
Items: action; button; cell; data
delay Syntax: delay = ["<repeat | once>","<interval>"];
Default: once with an interval of 0 seconds
Items: action
editstate Syntax: editstate = "<readonly | writeonly |
readwrite>";
Default: readwrite
Items: button; cell; check; combobox; field;
list; popup; radio
filename Syntax: filename = "<file name>";
Default: None
Items: data
fontcolor Syntax: fontcolor = ["<color name>"];
fontcolor = ["<R value>","<G value>",
"<B value>"];
Default: for check and radio, red
for all other items, the fontcolor set
in global characteristics, or "black"
if no preference set
Items: button; check; combobox; field; label;
line; list; popup; radio; tablet; page
characteristics; form characteristics
fontinfo Syntax: fontinfo = ["<font name>","<point
size>","<weight>","<effects>","<form>"];
* weight, effects, and form are optional
Default: the fontinfo set in global
characteristics, or "Helvetica 8 plain"
if no characteristics set
Items: box; button; check; combobox; field;
label; line; list; popup; radio; spacer;
tablet; page characteristics; form
characteristics
format Syntax: format = [<data type>,<format flag>,
<check flag>];
* format and check flags are optional,
and multiple flags are valid
Default: for data type - none
for format flag - depends on data type
for check option - depends on data type
Items: combobox; field; label; list; popup
group Syntax: group = "<group name | group reference>";
Default: None
Items: cell; combobox; list; popup; radio
Universal Forms Description Language [page 131]
help Syntax: help = "<item reference>";
Default: None
Items: button; check; combobox; field; label;
list; popup; radio; tablet
image Syntax: image = "<item reference>";
Default: None
Items: button; label; tablet
itemlocation Syntax: itemlocation =[<specification>],
[<specification>]...];
<specification> = "<modifier>",
"<itemtag>","<itemtag>"
* the second itemtag only to align
between modifiers
Default: for the first item - the top left corner
of the form
for all other items - vertically below
the previously created item and
horizontally at the left margin
Items: box; button; check; combobox; field;
label; line; list; popup; radio; spacer;
tablet
justify Syntax: justify = "<left | right | center>";
Default: for button and popup - center
for label - left
Items: button; label; popup; tablet
label Syntax: label = "<label text>";
Default: None
Items: check; combobox; field; list; popup;
radio; spacer; page characteristics;
form characteristics
labelbgcolor Syntax: labelbgcolor = ["<color name>"];
labelbgcolor = ["<R value>","<G value>",
"<B value>"];
Default: for items in the toolbar - the background
color of the toolbar
for other items - the background color
of the form
Items: check; combobox; field; list; radio
labelbordercolor Syntax: labelbordercolor = ["<color name>"];
labelbordercolor = ["<R value>",
"<G value>", "<B value>"];
Default: black
Items: check; combobox; field; list; radio
labelborderwidth Syntax: labelborderwidth = "<width>";
Default: 0 pixels
Items: check; combobox; field; list; radio
labelfontcolor Syntax: labelfontcolor = ["<color name>"];
Universal Forms Description Language [page 132]
labelfontcolor = ["<R value>",
"<G value>", "<B value>"];
Default: black
Items: check; combobox; field; list; radio;
page characteristics; form
characteristics
labelfontinfo Syntax: labelfontinfo = ["<font name>","<point
size>","<weight>","<effects>","<form>"];
* weight, effects, and form are optional
Default: Helvetica-8-plain
Items: check; combobox; field; list; radio
mimedata Syntax: mimedata = "<data>";
Default: none
Items: data
mimetype Syntax: mimetype = "<MIME type>";
Default: application/uwi_bin
Items: data
next Syntax: next = "<item reference>";
Default: when the form opens - the first
non-toolbar item in the form's
description that users can modify
when tabbing to subsequent items -
the next item in the form's
description that users can modify
when tabbing from the last item -
the first item in the form's
description that users can modify
(can be a toolbar item)
Items: button; combobox; check; field; list;
popup; radio; tablet
printsettings Syntax: printsettings = [<page list>,
<dialog settings>];
Default: the page list defaults to include all
pages in the form
the dialog defaults to "on", has the
following settings:
orientation = portrait
copies = 1
printpages active = on
printpages choices = all
Items: action, button, cell, page global
characteristics, form global
characteristics
saveformat Syntax: saveformat = "<mimetype>";
Default: application/uwi_form
Items: button; cell; form characteristics
scrollhoriz Syntax: scrollhoriz = "<never | always
| wordwrap>";
Universal Forms Description Language [page 133]
Default: never
Items: field
scrollvert Syntax: scrollvert = "<never | always | fixed>";
Default: never
Items: field
size Syntax: size = ["<width>","<height>"];
The unit of measurement is characters.
Default: see below (defaults are also used in
place of invalid and missing arguments)
Items Width Height Default bounding box
size
box 1 1 same as item
(smaller than one not allowed in either dimension)
button
(with label label same as item
text) width height
(with image image same as item
image) width height
check 1 1 max (1, label width)
x label height + 1
combobox max of 1 same as item
(label
width,
widest
cell)
field 60 1 max (field width,
label width)
x field height
+ label height
label
(label 1 1 same as item
empty)
(label label label
given) width height same as item
line 1 1 pixel same as item
(one dimension must be 0)
list max of number of same as item
(label cells, +1
width, if label
widest
cell)
Universal Forms Description Language [page 134]
popup max of 1 same as item
(label
width,
widest
cell)
radio 1 1 max (radio width,
label width)
x radio height +
label height
spacer
(no label) 1 1 same as item
(label label label same as item
given) width height
tablet
(no image) 1 1 same as item
(image) image image same as item
width height
thickness Syntax: thickness = "<thickness>";
Default: 1 pixel
Items: line
transmit Syntax: transmit = "<all | filter | none>";
Default: filter
Items: all items
transmitformat Syntax: transmitformat = "<MIME type>";
Default: application/uwi_form
Items: action; button; cell; form characteristics
transmititems Syntax: transmititems = ["<keep | omit>", "<item
type>","<item type>"...];
Default: keep
Items: action; button; cell
transmitoptions Syntax: transmitoptions = ["<keep | omit>",
"<option type>","<option type>"...];
Default: keep
Items: action; button; cell
triggeritem Syntax: triggeritem = "<item reference>";
Default: the item reference of the item that
triggered the "submit" or "done"
Items: in form global characteristics
type Syntax: type = "<task type>";
Default: link
Items: action; button; cell
url Syntax: url = ["<URL | item reference>",
["<URL>"],...];
Default: None
Universal Forms Description Language [page 135]
Items: action; button; cell
value Syntax: value = "<setting>";
Default: depends on item
Items: button; cell; check; combobox;
field; help; label; list; popup;
radio; tablet
version Syntax: version = <version number>;
Default: None
Items: in form global characteristics
Appendix B: Default Sizes
The following table shows the default basic item and bounding box
sizes.
Item Default Item Size Bounding Box Size
box width: 1 character Same as default item size
height: 1 character
Smaller than 1 not
allowed in either
dimension
button width: width of label Same as default item size
height: height of label
(label is in the value
option)
or size of embedded
image if it exists
check width: 1 character width: larger of 1
height: 1 character character and label
width
height: label height plus
1 character
(label is in the label
option)
combobox width: larger of label Same as default item
width and widest size (ii)
cell (iii)
height: 1 character
(label is in the label
option)
field width: 30 characters width: larger of item
height: 1 character width and label
width (ii)
height: height of item plus
height of label(ii)
Universal Forms Description Language [page 136]
(label is in the label
option)
label width: 1 character if Same as default item size
label empty,
otherwise
label width
height: 1 character if
label empty,
otherwise
label height
or size of embedded image
if it exists
line width: 30 character Same as default item size
height: 1 pixel
One dimension must
be 0 (i)
list width: larger of label width: larger of item
width and widest width and widest
cell (iii) cell (ii)
height: number of cells height: height of item
in list plus
height of label
(label is in the label (label is in the label
option) option)
popup width: larger of label Same as default item
width and widest size (ii)
cell (iii)
height: 1 character
(label is in the label
option)
radio width: 1 character width: larger of 1
height: 1 character character
and label width
height: label height plus
1 character
(label is in the label option)
spacer width: 1 character if Same as default item size
label empty,
otherwise
label width
height: 1 character if
label empty,
otherwise
label height
(label is in the label
option)
Universal Forms Description Language [page 137]
tablet width: 1 character if Same as default item size
tablet empty,
otherwise
value width
height: 1 character if
label empty,
otherwise
value height
or size of
embedded image
if it exists
Notes:
i) For line items, either height or width must be set to zero.
The thickness option specifies the thickness (in pixels)
of the line in the dimension containing zero (0). If both
settings are non-zero, the line size will default to one
character wide by one pixel thick.
ii) This includes a scroll bar if one appears.
iii) The cell's width comes from the cell's value option setting.
Appendix C: Grammar of the UFDL
This specification describes the grammar of the UFDL. It does not
describe the vocabulary of the language. This can be found in
sections '4 UFDL Form Items' and '5 UFDL Form Options'.
To completely understand the UFDL grammar, please use this appendix
in conjunction with the following sections of the guide:
- '2.4 Syntax of the UFDL'
- '2.5 UFDL Language Elements'
- '2.6 Processing Forms'
Much of the information in those sections and in this appendix is an
expansion of the material found in the white paper 'Lexical and
Syntactical Specification of the Universal Forms Description
Language (UFDL) Version 3.1'. You can find the white paper at the
following World Wide Web site: http://www.uwi.com/ufdl.htm.
C.1 Symbols
The production rules contain three types of symbols:
- simple terminal symbols
- complex terminal symbols
- non-terminal symbols
Universal Forms Description Language [page 138]
Simple Terminal Symbols
These symbols are UFDL operators and separators, and the keywords
new, page, global and version. They appear in bold face (and often
in a larger font size) in the production rules.
Complex Terminal Symbols
These symbols represent identifiers and values. They appear in
italics in the production rules.
Symbol Description
index a non-negative integer
name a page, item instance or option identifier. Names
must conform to the UFDL naming conventions for
user-defined identifiers.
type an item type. Types can be UFDL or user defined.
User-defined types must conform to the UFDL
naming conventions for user-defined identifiers.
qstring a double quoted string of characters
Non-terminal Symbols
These are variable strings of simple and complex symbols. They
appear as underlined words in the production rules where they are
defined. An example of a non-terminal symbol is Statement.
C.2 Production Rules
The syntax of a production rule is:
Non-terminal symbol ::= <expression>
where:
::= means 'is defined to be'
<expression> is a sequence of terminal and non-terminal symbols
that reduce to Non-terminal symbol.
Conventions
The <expression> can contain the following symbols:
- vertical bar ( | ) - separates reduction choices
- positive closure symbol ( + ) - the immediately preceding symbol
occurs one or more times
- Kleene's closure symbol ( * ) - the immediately preceding symbol
occurs zero or more times
Rules
The full set of UFDL production rules follows:
1) Form ::= Version Statement* Page+
Universal Forms Description Language [page 139]
2) Version ::= version = qstring;
3) Page ::= name = new page { Statement* Item* }
4) Item ::= name = new type { Statement* }
5) Statement ::= OptionName = RHS ;
6) OptionRef ::= OptionName| OptionName BracketList
7) BracketList ::= BracketList [ IndexType ] | [ IndexType ]
8) IndexType := index | OptionName
9) RHS ::= Compute | [ ComputeList ]
10) ComputeList ::= ComputeList , ComputeElement | ComputeElement
11) ComputeElement ::= RHS | OptionName= RHS
12) Compute ::= Expr | Decision ? Compute : Compute
13) Decision ::= Decision || AndDecision | AndDecision
14) AndDecision ::= AndDecision && NotDecision | NotDecision
15) NotDecision ::= ! Comparison | Comparison
16) Comparison ::= ( Decision ) | Expr Comparator Expr
17) Comparator ::= < | > | <= | >= | == | !=
18) Expr ::= Expr + Term | Expr - Term | Expr +. Term | Term
19) Term ::= Term * NFactor | Term / NFactor | NFactor
20) NFactor ::= Factor | - Factor
21) Factor ::= Value ^ NFactor | Value
22) Value ::= ( Compute ) | qstring | StaticRef |
StaticRef->DynamicRef
23) StaticRef ::= ItemTag . OptionRef | OptionRef
24) DynamicRef ::= DynamicRef->OptionRef | OptionRef
25) ItemTag ::= name . name | name
Addendum
These notes enhance understanding of the production rules and cover
points not included in the material referenced at the start of this
appendix.
File Inclusion
#include statements are resolved before the form is parsed.
Comments
The integrity of comment locations and formats is maintained
regardless of changes that occur during form processing.
Option References
A statement assigns a result, either constant or computed, to an
occurrence of an option name. It is unnecessary to define an option
name before using it in a statement; therefore, an option name
occurrence is created automatically by the first statement using it.
Decision Operator
The language definition allows the result of a decision operation
( ?: ) to be used in a mathematical calculation. The language
structure, though, syntactically forbids the use of logical
constructions in mathematical expressions. The result of a logical
construction is of type Boolean, and this is incompatible with
Universal Forms Description Language [page 140]
numerical types required in mathematical expressions.
However, Rule 21 specifies Compute between parentheses. This means
the result of a decision operation can be used in a mathematical
expression if the decision construct is in parentheses.
Appendix D: UFDL for C and C++ Programmers
This document is intended to introduce programmers to the syntax of
the UFDL. To do so, we will compare the UFDL to the C programming
language, and point out many of the similarities in syntax and
structure that exist between the two languages, as well as some of
the differences.
Be aware that this document outlines one way of modelling these
similarities and differences, and that a number of other approaches
could be used.
D.1 Procedural vs. State Language
Unlike C, the UFDL is a state language. Where C describes a
procedure that is followed, the UFDL describes a state that is
maintained. All of the statements in a UFDL form are always
maintained as being true.
As a result, computations are constantly updated throughout the
form. For instance, imagine a form with a field called total, the
value of which is based on adding the values of five other fields.
Whenever a value is entered (or changed) in one of those five
fields, the total field will be instantly updated to reflect that
change. In this, the UFDL acts much like a spreadsheet.
D.2 Globals and Functions (Pages)
When coding a form, the first statements define the global
characteristics and includes. These are much like global variables
and includes in C. The next thing defined is the first page of the
form, which parallels a function in a C program. The table below
demonstrates these similarities:
C UFDL
int version=3; version="3.2.0";
char *bgColor[]={"0","0","255"}; bgcolor=["0", "0", "255"];
#include "header.h" #include "header.frm"
void page_1() page_1=new page
{ {
<code> <code>
} }
Universal Forms Description Language [page 141]
Notice the similarities in syntax as well. Statements are ended with
a semi-colon. New pages (or functions) do not end with a semi-colon,
and the code for each begins and ends with braces.
Within each page, the UFDL allows the definition of page-specific
characteristics similar to function specific variables. You can also
define items, which can be thought of as instances of predefined
structures or cases. Within each instance, there are a number of
options that can be set. The following table illustrates this:
C UFDL
struct label{
char *value;
char **fontcolor;
char *transmit;
char **bgcolor;
};
void page_1() page_1=new page
{ {
struct label *label_1=NULL; bgcolor=["255","239",
char *bgcolor[] = {"255","239","213"}; "213"];
label_1=(struct label*)malloc label_1=new label
(sizeof(struct label)); {
label_1->value=strdup("This is a label"); value="This is a label";
label_1->(fontcolor[0])=strdup("255");
fontcolor=["255","255","255"];
label_1->(fontcolor[1])=strdup("255"); transmit="none";
label_1->(fontcolor[2])=strdup("255");
label_1->transmit=strdup("none");
label_1->(bgcolor[0])=strdup(bgcolor[0]); }
label_1->(bgcolor[1])=strdup(bgcolor[1]);
label_1->(bgcolor[2])=strdup(bgcolor[2]);
} }
In this example, value, fontcolor, and transmit are options for the
item label_1. Notice that they are contained within an opening and a
closing brace, which makes it clear, without dereferencing, which
item they belong to (this is similar to the with statement in
Pascal). Also note that bgcolor is a page characteristic that is
automatically assigned to label_1.
Additional pages can be defined just like additional functions, and
there is no limit to the number of pages you can have, nor to the
number of items you can have within a page. Additionally, it is
possible to create custom items and options, allowing for greater
flexibility.
D.3 References and Dereferencing
Specific items or option can be referenced through the use of a
reference string. Additionally, the values of options can be
dereferenced in a manner similar to C.
Universal Forms Description Language [page 142]
C UFDL
Structure Declaration Item Declaration
struct label{ label_1=new label
struct label *value; {
char *justify; value="label_2";
}; justify="center";
}
struct label *label_1; label_2=new label
struct label *label_2; {
justify="right";
label_1->value=label_2; }
label_1->justify=strdup("center");
label_2->justify=strdup("right");
References References
label_1->justify is center label_1.justify is center
label_1->value->justify is right label_1.value->justify is right
no equivalent page1.label_1.justify is center
Note that the inclusion of page1 is optional. Including it allows
the item or option to be referenced from a different page. Where C
requires you to pass values between functions by using parameters,
the UFDL allows you to access any value from any page on the form by
using a direct reference.
D.4 Arrays
Many of the options in the UFDL are set using array structures.
Specific elements in these arrays are referenced just as they would
be in C.
C UFDL
Array Declaration Option Declaration
char *format[2][2];
format=["integer",range=["1","10"]];
format[0][0]=strdup("integer");
format[0][1]=NULL;
format[1][0]=strdup("1");
format[1][1]=strdup("10");
Element Reference Element Reference
format[1][0] format[1][0] or
format[range][0]
Note the second Element Reference in the UFDL. This reference is
based on assigning a name to an element or set of elements within
the array. In this case, the name range was given to the second set
of elements. This allows you to access the elements of an array
without having to know the order of those elements.
Universal Forms Description Language [page 143]
There is no limit to the depth allowed an array in the UFDL-you can
have infinitely nested arrays. Additionally, the UFDL does not
create unnecessary blocks in memory. For instance, in the above
example format[0][1] was assigned to be NULL in the C code. This is
because this portion of the array is not used. In the UFDL, that
portion of the array is never created. This means that the UFDL uses
significantly less memory to store multi-dimensional arrays.
D.5 Assignment
The UFDL has a single data type: the string. All values, be they
integer, character, or float, are stored as literal strings. In
order to assign literal strings, quotes are used just as in C.
For example:
C UFDL
value=strdup("This is a literal string"); value="This is a
literal string";
size[0]=strdup("10"); size=["10","10"];
size[1]=strdup("10");
Note that you do not need to use any of the string functions such as
strdup. Memory management is handled automatically. Assigning a
string to an option automatically copies the string and disposes of
any previous value for that option. Additionally, the full list of
elements can be assigned to an array at any time in the UFDL code.
In C, this is only possible when you first declare your arrays
(see the size example above).
Appendix E: Glossary
Absolute Positioning
Absolute positioning places items in set locations on the form. This
form of positioning uses an x-y coordinate system to specify where,
in relation to the upper-left corner of the form, the item should be
placed. Absolute positioning allows for drag-and-drop form designer
functionality. See Also: Relative Positioning
Automatic Action
Automatic actions are background actions that you can set your form
to carry out without user prompting. These actions can be set to
occur after a specific amount of time, or to repeat periodically.
Use automatic actions to create effects such as periodic interfacing
with databases. For example:
ping_action = new action
{
delay = ["repeat", "120"];
type = "submit";
url = ["http://www.server.domain/cgi-bin/status"];
Universal Forms Description Language [page 144]
}
Alignment Modifiers
This is a group of modifiers used in relative positioning. They are
used to set locators that align items in relation to each other. See
Also: Relative Positioning, Locators
Bounding Box
An unseen rectangular area surrounding each item and including all
elements of the item (including built-in labels and borders). Used
in the relative ositioning scheme for determiniing the "edge" of an
item.
Build Order
When you create items on a form, the order in which they are created
forms a sequence. The first item you create is the first item in the
sequence, the second item is second in the sequence, and so on. This
sequence is called the build order. The build order can affect
relative positioning.
Compression
You can set up forms to submit and save as compressed files. See the
descriptions or the saveformat and transmitformat options.
Computation
See: Formulas
Custom Item
Custom items are items that are not part of the standard UFDL. You
define these items yourself. Custom items are ignored by the a UFDL
parser, and are never visible on the form. Use custom items to
integrate the form with other applications. See Also: Custom
Options, Hidden Items
Custom Option
Custom options are options that are not part of the standard UFDL.
You create these options yourself. Custom options are ignored by a
UFDL parser, and ever affect the appearance of an item. Use custom
options to integrate your form with other applications. See Also:
Custom Items
Expansion Modifiers
This is a group of modifiers used in relative sizing. They are used
to set locators that adjust the size of items in relation to other
items on the form. See Also: Extent Modifier, Locators
Extent Modifier
Universal Forms Description Language [page 145]
This modifier is used in both normal and relative positioning. It
is used to set locators that set the size of items in pixels. See
Also: Expand Modifiers, Locators
Filtering
You can set up forms to filter out specific item types, option
types, or items when they are transmitted. This can be useful for
eliminating unnecessary information when the form is being
transmitted to another application. See the descriptions for the
transmit, transmititems, and ransmitoptions options. See Also:
Compression
Formulas
Formulas allow you to add math or logic to your form. You can use
them to add values or make decisions based on user input. Also
referred to as computations or logical operations.
Global Settings
Global settings are used to set options for the whole form. Each
item in the form will reflect that option setting, unless the same
option is also set for that page or item.
Hidden Items
Hidden items are not independently visible on the form. However, in
some cases they may contribute to the appearance of other form
items. The hidden items are: data items, cells, action items, help
items, and custom items.
Identifiers
Identifiers are used to uniquely identify a page, item, option, or
option element in the form. For a discussion of the character set
you may use when creating identifiers, see the section called
Identifiers in '2. The Universal Forms Description Language'.
Include
The #include statement allows you to "include" external files in a
form. These files must be in a UFDL format that is compatible with
the form. A UFDL parser must insert include files into forms at the
place marked by an #include statement.
Input Focus
When a user views a form, the input focus is the focus that moves
from item to item in the form when the user presses the TAB key.
Item Tag
Each item has a unique item tag, or name, which is used to identify
Universal Forms Description Language [page 146]
that item.
Locators
Locators are used to set both the locations of an item on the page
and any relative or extent sizing that should apply to the item.
Modifier
Modifiers are combined with item tags to create locators. Modifiers
describe how an item should be positioned in relation to its
reference items. For example, after, below, left-to-left, and so on.
See Also: Locators, Reference Items
Page
Each form can be composed of any number of pages, just like a paper
form. Each page is identified with a page tag, begins with an open
brace ({) and ends with a close brace (}). All forms must have at
least one page.
Page Settings
These settings set global option settings for all items on the page
(unless an individual item description overrides the setting). Page
settings override global settings, but are overridden by options set
for individual items.
Page Tag
Each page has a unique page tag, or name, which is used to identify
that page.
Reference
References allow you to identify a specific option by providing a
"path" to it. This means that you can refer directly to a specific
option anywhere in the form. A reference is constructed by combining
the page tag, item tag, and option name that will point to the
option you want. For example, page1.title_label.value points to the
value option of the title_label on page one.
Reference Items
When using relative positioning or sizing, you will need to use some
items as reference points. These reference points will be used as
anchors that set either where an item is positioned on the form or
how large the item is. If the reference items are moved or change
size, the item using them as anchors may also move or change size.
See Also: Relative Positioning, Relative Sizing
Relative Positioning
Relative positioning places items on the form in relation to other
items. This means that items will move on the form if their
Universal Forms Description Language [page 147]
reference item moves. Relative positioning is useful for ensuring
cross-platform compatability. See Also: Absolute Positioning,
Reference Items
Relative Sizing
Relative sizing adjusts the size of items on the form in relation to
other items. This means that items will change size on the form if
their reference item moves or changes size. Relative sizing is
useful for ensuring that the edges of your items line up on the
form. See Also: Reference Items
Required Status
The required status is part of the format option. It determines
whether the user of a form is required to enter information into an
item. The required status can be set to "optional" or "mandatory".
Tab Order
This is the order in which the user will move through the item on
the form by pressing the TAB key. The tab order only includes those
items that take user input, such as fields, buttons, and so on. You
can set the tab order yourself.
Version Number
This option records the version number of the UFDL that was used to
create the form. It is only available in the global settings.
Author Contact Information
David Manning
dmanning@uwi.com
voice. 250-479-8334
fax. 250-479-3772
post. David Manning
UWI Unisoft Wares Inc.
1095 McKenzie Avenue, 4th Floor
Victoria, B.C., Canada
V8P 2L5
Universal Forms Description Language [page 148]