idnits 2.17.1 draft-gordon-ufdl-spec-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 3 longer pages, the longest (page 45) being 113 lines == It seems as if not all pages are separated by form feeds - found 231 form feeds but 238 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 2.6 Security' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 91 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 14 instances of too long lines in the document, the longest one being 50 characters in excess of 72. ** There are 912 instances of lines with control characters in the document. == There are 8 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 366: '...ich elements are REQUIRED, RECOMMENDED...' RFC 2119 keyword, line 367: '... OPTIONAL in an implementation. The...' RFC 2119 keyword, line 368: '... the language is REQUIRED is whether t...' RFC 2119 keyword, line 371: '...t below, all elements are REQUIRED. An...' RFC 2119 keyword, line 372: '...t include an element MUST interoperate...' (10 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 20 has weird spacing: '... of six month...' == Line 2525 has weird spacing: '..., based type...' == Line 2526 has weird spacing: '...ititems throw...' == Line 2527 has weird spacing: '...g their out...' == Line 2531 has weird spacing: '...ased on items...' == (86 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1998) is 9384 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '0' on line 12525 looks like a reference -- Missing reference section? '1' on line 12525 looks like a reference -- Missing reference section? '2' on line 12505 looks like a reference -- Missing reference section? 'PD1' on line 5314 looks like a reference -- Missing reference section? '45' on line 10825 looks like a reference -- Missing reference section? '90' on line 10825 looks like a reference Summary: 13 errors (**), 0 flaws (~~), 10 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT 2 David Manning, Richard Bennett, John Boyer, 3 Sonja McLellan, Michael Mansell 4 August 1998 5 Expires: February 04, 1999 7 Universal Forms Description Language Specification 8 Version 4.0.1 9 11 Status of this Memo 13 This document is an Internet-Draft. Internet Drafts are 14 working documents of the Internet Engineering Task Force 15 (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum 20 of six months and may be updated, replaced, or obsolete 21 by other documents at any time. It is inappropriate to use 22 Internet-Drafts as reference materials or to cite them 23 other than as "work in progress." 25 To view the entire list of current Internet-Drafts, please 26 check the "1id-abstracts.txt" listing contained in the 27 Internet Drafts Shadow Directories on ftp.is.co.za (Africa), 28 ftp.nordu.net (Europe), munnari.oz.au (Pacific Rim), 29 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast) 31 Abstract 33 The Universal Forms Description Language (UFDL) describes complex 34 business forms for use over the Internet. The objective of the UFDL 35 is to enable the creation of cross-platform Internet business forms 36 that (1) contain both the complex logic and precise layout that 37 administrators require, (2) are simple to maintain and distribute, 38 and (3) integrate easily with existing business systems. As more 39 and more business is done over the Internet, the need for a form 40 description language that incorporates these features grows. HTML 41 is designed for Internet pages, and is severely limited as a form 42 language. This document specifies the vocabulary, syntax, and 43 meaning of the UFDL. 45 CONTENTS 47 1. INTRODUCTION 48 1.1 Introduction to the UFDL 49 1.2 UFDL Documentation 50 1.2a How This Document is Organized 51 1.2b Other UFDL Documentation 52 1.3 Requirement Levels for UFDL Elements 53 1.4 Implied Semantics for UFDL Viewers 54 1.5 Security Considerations 55 1.6 Responding to Errors in the Form Description 57 2. INTRODUCTION TO THE UNIVERSAL FORMS DESCRIPTION LANGUAGE 58 2.1 What is UFDL? 59 2.2 Features of UFDL Forms 60 2.3 Description of a UFDL Form 61 2.3a What is a Page? 62 2.3b What is an Item? 63 2.3c What is an Option? 64 2.3d Including External Files 65 2.3e Unrecognized Items and Options 66 2.4 Syntax of UFDL 67 2.4a Basic Syntax Rules 68 2.4b Form Definition 69 2.4c Page Definition 70 2.4d Item Definition 71 2.4e Item Size 72 2.4f Item Placement 73 2.4g Toolbar Definition 74 2.4h Option Definition 75 2.4i Literals 76 2.4j References to Other Options 77 2.4k Relative Page Tags and Item Tags 78 2.4l Operations 79 2.4m User Events and Changes of State 80 2.4n Arrays 81 2.4o Defining Tabbing and Paging 82 2.4p Including External Files 83 2.5 UFDL Language Elements 84 2.5a Identifiers 85 2.5b Custom Item Types and Custom Option Names 86 2.5c Reserved Words 87 2.5d Quoted Strings 88 2.5e Binary Data 89 2.5f Comments 90 2.6 Security 91 2.7 Filters 92 2.8 Processing Forms 93 2.8a Include Statements 94 2.8b Expressions 96 3. UFDL GLOBAL AND PAGE SETTINGS 97 3.1 Global Settings 98 3.2 Page Settings 100 4. UFDL FORM ITEMS 101 4.1 action 102 4.2 box 103 4.3 button 104 4.4 cell 105 4.5 check 106 4.6 combobox 107 4.7 data 108 4.8 field 109 4.9 help 110 4.10 label 111 4.11 line 112 4.12 list 113 4.13 popup 114 4.14 radio 115 4.15 signature 116 4.16 spacer 117 4.17 tablet 118 4.18 toolbar 119 4.19 121 5. UFDL FORM OPTIONS 122 5.1 activated 123 5.2 active 124 5.3 bgcolor 125 5.4 bordercolor 126 5.5 borderwidth 127 5.6 coordinates 128 5.7 data 129 5.8 datagroup 130 5.9 delay 131 5.10 editstate 132 5.11 filename 133 5.12 focused 134 5.13 fontcolor 135 5.14 fontinfo 136 5.15 format 137 5.16 group 138 5.17 help 139 5.18 image 140 5.19 itemlocation 141 5.20 justify 142 5.21 label 143 5.22 labelbgcolor 144 5.23 labelbordercolor 145 5.24 labelborderwidth 146 5.25 labelfontcolor 147 5.26 labelfontinfo 148 5.27 mimedata 149 5.28 mimetype 150 5.29 mouseover 151 5.30 next 152 5.31 previous 153 5.32 printsettings 154 5.33 saveformat 155 5.34 scrollhoriz 156 5.35 scrollvert 157 5.36 signature 158 5.37 signdatagroups 159 5.38 signer 160 5.39 signformat 161 5.40 signgroups 162 5.41 signitemrefs 163 5.42 signitems 164 5.43 signoptionrefs 165 5.44 signoptions 166 5.45 size 167 5.46 thickness 168 5.47 transmitdatagroups 169 5.48 transmitformat 170 5.49 transmitgroups 171 5.50 transmititemrefs 172 5.51 transmititems 173 5.52 transmitoptionrefs 174 5.53 transmitoptions 175 5.54 triggeritem 176 5.55 type 177 5.56 url 178 5.57 value 179 5.58 version 180 5.59 182 6. UFDL FORM VIEWER DIRECTIVE 183 6.1 #include 184 6.2 #optinclude 186 7. UFDL FUNCTIONS 187 7.1 String Functions 188 7.1a countLines 189 7.1b replace 190 7.1c strlen 191 7.1d strmatch 192 7.1e strpbrk 193 7.1f strrstr 194 7.1g strstr 195 7.1h substr 196 7.1i tolower 197 7.1j toupper 198 7.1k trim 199 7.1l URLDecode 200 7.1m URLEncode 201 7.2 Math Functions 202 7.2a abs 203 7.2b acos 204 7.2c annuity 205 7.2d asin 206 7.2e atan 207 7.2f ceiling 208 7.2g compound 209 7.2h cos 210 7.2i deg2rad 211 7.2j exp 212 7.2k fact 213 7.2l floor 214 7.2m ln 215 7.2n log 216 7.2o mod 217 7.2p pi 218 7.2q power 219 7.2r rad2deg 220 7.2s rand 221 7.2t round 222 7.2u sin 223 7.2v sqrt 224 7.2w tan 225 7.3 Utility Functions 226 7.3a applicationName 227 7.3b applicationVersion 228 7.3c applicationVersionNum 229 7.3d decimal 230 7.3e formatString 231 7.3f isValidFormat 232 7.3g set 233 7.3h toggle 234 7.4 Time and Date Functions 235 7.4a date 236 7.4b dateToSeconds 237 7.4c day 238 7.4d dayOfWeek 239 7.4e endOfMonth 240 7.4f hour 241 7.4g minute 242 7.4h month 243 7.4i now 244 7.4j second 245 7.4k time 246 7.4l year 248 APPENDIX A: QUICK REFERENCE TABLES 249 A.1 Table of Items and Form and Page Characteristics 250 A.2 Table of Options 252 APPENDIX B: DEFAULT SIZES 254 APPENDIX C: UFDL FOR C AND C++ PROGRAMMERS 255 C.1 Procedural vs. State Language 256 C.2 Globals and Functions (Pages) 257 C.3 References and Dynamic Option Reference 258 C.4 Arrays 259 C.5 Assignment 261 APPENDIX D: GLOSSARY 263 AUTHOR CONTACT INFORMATION 265 1. INTRODUCTION 267 1.1 Introduction to the UFDL 269 This document specifies the Universal Forms Description Language 270 (UFDL), which describes complex business forms for use over the 271 Internet. The objective of the UFDL is to enable the creation of 272 cross-platform Internet business forms that (1) contain both the 273 complex logic and precise layout that administrators require, (2) 274 are simple to maintain and distribute, and (3) integrate easily with 275 existing business systems. This document specifies the vocabulary, 276 syntax, and meaning of the UFDL. 278 Since more and more business is being done over the Internet, the 279 need for a form description language that incorporates the 280 complexities of business systems is growing. Typically, an 281 electronic business form is part of a process-intensive 282 administration system. Users or server modules populate forms with 283 data, the forms are distributed according to a work flow plan, and 284 the data is stored in a database (or, in departments that have no 285 complete electronic solution, the form is printed for storage). The 286 forms, which can contain hundreds of input items, need to validate 287 the data they receive, perform calculations and other logical 288 operations, and integrate with existing data management systems. 289 Today, most Internet forms are inadequate and are being created with 290 HTML. 292 HTML is designed for the easy display of Internet pages. As a 293 result, HTML is very good at creating the layout for web sites and 294 has become the standard for web pages. Web designers and IS 295 organizations are now trying to push HTML beyond what it was 296 intended to do. HTML forms work well for collecting basic 297 information over the Internet. However, most business forms are much 298 more complex than the typical HTML order form. 300 HTML was not designed to collect, validate, manipulate, or store 301 information. In order to build significant intelligence into an HTML 302 form, a developer has to use JavaScript. Business forms also may 303 need to travel through nodes in distribution chains, being viewed or 304 changed by people along the way. HTML forms submit merely the data 305 they've collected-the user interface and intelligence don't 306 accompany it, and so make it difficult to create a workflow system 307 for the form. HTML forms also have a fairly inflexible layout, and 308 it's impossible to create precise, complex HTML forms and print them 309 the way people are used to. 311 The UFDL was designed specifically for Internet business forms. It 312 describes all components of a complex form: user interface, 313 intelligent features, and input data. A UFDL form can be transmitted 314 whole or in part from node to node in a distribution chain. The 315 UFDL's precise layout specifications allow users to create and print 316 forms that replicate the paper forms they're used to. The UFDL 317 includes complex business logic so that intelligent features like 318 user-input checking, calculations, and in-form decisions are part of 319 the form itself, rather than a separate script, and travel with the 320 form to the next user. The UFDL allows developers to extend the 321 language to interface with other applications by adding their own 322 customized information to forms. The syntax of the UFDL is 323 high-level and easy to learn, but at the same time incorporates the 324 logic needed for business transactions. C and Java programmers will 325 recognize many features of the syntax. 327 1.2 UFDL Documentation 329 This section outlines how this document is organized, and directs 330 readers to other documents on the Universal Forms Description 331 Language for further information. 333 1.2a How This Document is Organized 335 The UFDL Specification is intended both for an academic audience 336 and for form developers and people writing applications that use 337 UFDL forms. 339 For an introduction to the language and its elements, see Part 2: 340 Introduction to the Universal Forms Description Language. It 341 explains the concepts behind the UFDL and specifies the components 342 of a UFDL form. It delineates the UFDL syntax and explains the 343 language elements. 345 For a full description of form global settings, form items, form 346 options, and directives for form viewers, see parts 2, 3, 4, and 5. 348 For the Backus-Naur Form (BNF) of the UFDL, see 'Appendix A: 349 Grammar of the UFDL'. C Programmers may find it useful to review 350 'Appendix C: UFDL for C and C++ Programmers'. 352 1.2b Other UFDL Documentation 354 Those who want to find out more about the grammar behind the UFDL 355 may want to view or download the Lexical and Syntactical 356 Specification for the UFDL. 358 Both of these documents are available at http://www.uwi.com/UFDL 360 1.3 Requirement Levels for UFDL Elements 362 This specification does not contain extraneous material, and 363 therefore most implementers of the UFDL will want to include all 364 elements specified here. However, not all elements are required, 365 though all are suggested. 366 This section specifies which elements are REQUIRED, RECOMMENDED, and 367 OPTIONAL in an implementation. The criterion for determining whether 368 an element of the language is REQUIRED is whether the exclusion of 369 the element would prevent people from filling and transmitting the 370 form. 371 Unless specified in the list below, all elements are REQUIRED. An 372 implementation that does not include an element MUST interoperate 373 with another implementation that does include the element (though 374 perhaps with reduced functionality). In the same vein, an 375 implementation that does include the element MUST interoperate 376 with one that does not (except, of course, for the feature the 377 element provides). Also, before deciding to ignore an element that 378 is RECOMMENDED, an implementor must understand the implications 379 of not including the element. 380 RECOMMENDED Elements (Elements that implementors SHOULD include) 381 - bgcolor option 382 - fontcolor option 383 - labelbgcolor option 384 - labelfontcolor option 385 - next option 386 - previous option 387 - printsettings option 388 OPTIONAL Elements (Elements that implementors MAY include) 389 - help item 391 - bordercolor option 392 - borderwidth option 393 - help option 394 - labelbordercolor option 395 - labelborderwidth option 397 - #include directive 398 Note: For a definition of the words REQUIRED, RECOMMENDED, OPTIONAL, 399 MUST, SHOULD, and MAY as used in this section, see RFC 2119. 401 1.4 Implied Semantics for UFDL Viewers 403 There are a few behaviors that are "implied" but not explicit in 404 the UFDL, and that are defining features of the UFDL. This section 405 outlines those behaviors, and should be considered part of the UFDL 406 Specification. 407 Temporary Files 408 A viewer that uses UFDL forms may create temporary files in the 409 following locations: 410 - web browser's temp directory 411 - Windows temp directory 412 - viewer's temp directory 413 A viewer MUST NOT create temporary files in any other location 414 on a user's computer. This prevents system files or permanent 415 user files from being at risk if they're not in temp directories. 416 A viewer may delete files from the three temporary directories 417 listed above at its discretion, but it MUST delete ONLY files that 418 are older than the last reboot of the operating system, or that it 419 can positively identify as one of its own temporary files. 420 The following UFDL form events may cause a UFDL viewer to create 421 and/or delete temporary files: Opening a form; Closing a form; 422 Submitting a form (a transaction of type "submit" or "done"); 423 Emailing a form (if a viewer supports emailing forms); Enclosing 424 files; Displaying enclosures. 425 Permanent Files 426 Certain UFDL form operations require a viewer to read or create 427 permanent files. They are: Enclosing a File; Extracting a File; 428 and Saving a form. Only button and cell items can initiate these 429 operations. Automatic actions MUST NOT initiate actions that 430 create permanent files on a user's computer. 432 When a viewer performs an enclose, extract, or save operation, it 433 MUST conform to the restrictions that follow. 435 Enclosures: When the user activates an enclose button or cell, the 436 viewer must prompt the user with a file browser so that the user 437 can choose which file to enclose. This file browser must allow the 438 user to cancel the enclose transaction without writing the 439 enclosure into the form. Users may choose to enclose any files to 440 which their operating system gives them access. 442 Extractions: When the user activates an extract button or cell, 443 the viewer must prompt the user with a file browser so that the 444 user may choose both a location and a name for the file that's 445 being extracted. Other than the usual restrictions on file names 446 that the user's operating system imposes, the viewer must not 447 restrict the file name the user chooses. If the user specifies a 448 file name that already exists, then the viewer must warn the user 449 that it exists, and ask the user whether to overwrite the existing 450 file. The user must be able to cancel the extract operation before 451 the viewer has written the permanent file. 453 Saves: When the user activates a save button or cell, the viewer 454 must prompt the user with a file browser so that the user may 455 choose both a location and a name for the saved form. (Save acts 456 like "Save As".) Other than the usual restrictions on file names 457 that the user's operating system imposes, the viewer must not 458 restrict the file name the user chooses. If there is already a 459 file with the file name that the user specifies, then the viewer 460 must warn the user that it exists, and ask the user whether to 461 overwrite the existing file. The viewer must allow the user to 462 cancel the save operation before the viewer has written the 463 permanent file. 465 These rules have been created in order to allow users to perform the 466 enclosures, extractions, and saves necessary when completing 467 business forms, while at the same time protecting their computers by 468 (a) limiting temporary files to temp directories, and (b) preventing 469 uploads and downloads that users are not aware of. 471 1.5 Security Considerations 473 The UFDL specifies the description of a form, but not the transport 474 protocol for transmitting it. Any trasmission security issues that 475 exist for the transport protocol submitting the form (for example, 476 those used by mail programs and web browsers) exist when 477 transmitting a UFDL form. (Note, however, that UFDL forms can be 478 compressed using a compression algorithm before they are submitted. 479 For more information, see the transmitformat option description.) 481 UFDL forms cannot invoke programs on local computer drives. In 482 addition, a UFDL viewer must save temporary files to standard 483 temp directories only, as outlined in '1.4 Implied Semantics' above. 484 A UFDL Viewer may only read and write permament files under strict 485 conditions and then only with the user's knowledge (through 486 presenting a file browser); see '1.4 Implied Semantics' for more 487 information. 489 1.6 Responding to Errors in the Form Description 491 Any UFDL form interpreter must parse a UFDL form for non-compliance 492 to the UFDL specification. This debugger should treat 493 non-compliances in the following manner: 495 Flag as Warnings - All item types and option types that are not part 496 of the UFDL. These must be flagged as warnings and not as errors 497 because the UFDL allows developers to create custom items and 498 options for inserting application-specific information into forms. 499 Forms containing non-compliances that generate warning messages may 500 still be displayed. The non-compliances must be ignored when 501 displaying the form, and the defaults used instead (if applicable). 502 A UFDL Viewer may implement a mechanism that allows users to turn 503 off the warning messages. 505 Flag as Errors - Anything that might (but also might not) adversely 506 affect the appearance or functionality of the form. Forms that 507 contain non-compliances that might affect the appearance or 508 functionality of the form may be displayed. The non-compliances 509 must be ignored, and the defaults (if applicable) must be used 510 when displaying the form. 512 Flag as Fatal Errors - Anything that will adversely affect the 513 appearance or functionality of the form. Forms containing 514 non-compliances that generate fatal error messages must not be 515 displayed. 517 In addition, the UFDL debugger must check the version number of the 518 form it parses. The version number denotes which version of the UFDL 519 specification the form complies with. The parser must check for 520 non-compliances based on the version of the UFDL that the form was 521 written with. This provides backwards compatibility. 522 ------ 524 2. Introduction to the Universal Forms Description Language 526 2.1 What is UFDL? 528 Summary 530 The Universal Forms Description Language (UFDL) is a language that 531 describes complex Internet business forms much the way HTML 532 describes web pages. It is cross-platform, easy to learn, and its 533 features are tailored to business needs. 534 Note: Because UFDL version 4.0 includes the start value element 535 in an option name, any code written to work with the UFDL BNF 536 version 3.3.1 or earlier will not be able to parse a version 4.0 537 form. 539 Details 540 UFDL is a platform-independent, high-level language that 541 describes Internet business forms. It was designed specifically 542 for creating forms that are capable of replacing paper forms 543 systems. That is, it creates forms that: 544 - Create auditable records, by viewing a form as an object that 545 includes layout instructions and data, and that can be passed 546 whole from node to node in a distribution chain, archived, and 547 retrieved later for verification. 548 - Let users work offline or online. 549 - Perform logical operations, functions, and other behavioral 550 changes based on user events. 551 - Give users editing and error checking tools. 552 - Allow users to digitally sign the whole form or parts of the 553 form. 554 - Appear the same on any platform and under any screen resolution 555 and system font size. 556 - Interface with other applications. 558 UFDL incorporates the following design concepts: 560 Familiar Syntax 561 UFDL is easy to pick up, because it is syntactically similar to 562 two industry standard programming languages: C++ and Java. Here 563 is the description of a very simple UFDL form: 565 version = "3.2.0"; 566 bgcolor = ["ivory"]; 567 page_1 = new page 568 { 569 body_label = new label 570 { 571 value = "This is a UFDL form."; 572 } 573 } 575 Essentially, the form consists of one or more pages. A page 576 contains zero or more items, like the label item in the example 577 above. The items can be made from item types that are part of UFDL 578 (labels, buttons, fields, automatic actions and so on), or from 579 item types form designers create themselves. Pages and item types 580 have certain default characteristics that form developers can 581 modify by specifying various options. 583 Declarative Language 585 Statements in a UFDL form description are always maintained as 586 being true, much as formula fields in a spreadsheet are maintained 587 as true. The simplest example of this is a total field that adds up 588 the contents of various dollar fields in a form. If one of the 589 dollar fields changes, so does the total field. 591 What makes UFDL different from languages like C++ and Java in this 592 respect is that the constant evaluation of dependencies is inherent 593 in the language. A UFDL form requires no special procedures to be 594 written in order to run evaluations; the evaluations run 595 automatically whenever dependent data changes. 597 Extensible Syntax 599 UFDL was designed to be easily extensible for both form developers 600 and the creators of UFDL. 602 - Form developers can create their own item and option types 603 within forms (although currently they cannot set up inherited 604 attributes for each type they create). 605 - The authors of UFDL can add new features to each new version of 606 UFDL. 608 Open Protocol 610 UFDL is an open protocol. This gives developers the freedom to 611 manipulate UFDL forms any way they want. Scripts can be written to 612 dynamically create forms, modify forms, or extract specific 613 information from forms. UFDL forms can themselves make requests to 614 databases and populate themselves with the information returned. 615 This flexibility allows developers to integrate UFDL forms into any 616 application. 618 People with knowledge of C or C++ may wish to refer to Appendix D: 619 UFDL for C and C++ Programmers. This appendix outlines UFDL's 620 similarities to those languages. 621 ------ 623 2.2 Features of UFDL Forms 625 A UFDL form looks and behaves just the way you imagine an 626 electronic form should. It can contain graphical elements, 627 modifiable fields, and action items. You can organize a UFDL form 628 into pages similar to the pages in a paper form and you can include 629 navigational aids such as toolbars, tabbing instructions, and 630 scroll bars. In addition, you can code the form to make logical 631 decisions, to interface with other applications, and to 632 automatically format and check user's entries. 634 A desktop form viewer application displays the forms. This UFDL 635 form viewer allows users to enter input, enclose and view external 636 files, and print and save forms. When it is convenient, the user 637 can perform a simple action, such as pressing a button, to submit 638 the completed form to an application for processing. 640 Some of the features that make UFDL forms ideal for every-day 641 business use are outlined here. 643 Versatile Form Design 645 UFDL is very versatile. It provides many features you can use to 646 customize both the appearance and functionality of your form. 648 Absolute and Relational Positioning Schemes 650 UFDL supports both an absolute positioning scheme and a relational 651 positioning scheme. The absolute positioning scheme allows a form 652 designer to place visible form items in fixed locations on a form. 653 This is useful for beginners and for GUI design applications that 654 use a drag-and-drop method for designing forms. But an absolute 655 positioning scheme is not a cross-platform solution. Used in 656 conjunction with relational positioning, however, it can create 657 modularized blocks of a form that can be easily moved around. 659 UFDL's relational positioning scheme allows designers to create 660 forms that appear the same on any platform. It aligns visual 661 elements in relation to other visual elements on the form, ensuring 662 forms look consistent on all computers and at all screen 663 resolutions. If an item changes size-either to accommodate a 664 dynamically created value or a system font size-items aligned to it 665 will shift in relation to it. This relational positioning scheme is 666 flexible, giving developers freedom to create original layouts. 668 Support for User-Defined Objects 670 UFDL lets designers define their own form objects. These objects 671 have no visible properties and initiate no actions, which means 672 that form developers can store specialized information in the form 673 without harming its appearance or behavior. A form viewer 674 application respects references to custom objects in the form 675 definition, allowing a custom object to accumulate information and 676 also allowing other elements in the form to be altered according 677 to the custom object's contents. 679 Input and Format Control 681 UFDL permits form designers to specify an item's availability, edit 682 state, and input and output formats. This means the form can 683 perform much of the data checking and formatting typically 684 performed by form processing applications. 686 Digital Signatures 688 Version 4.0 and higher of UFDL supports digital signatures, for 689 secure, tamper-proof documents. Digital signatures are incorporated 690 into the description of the form, and allow the developer to 691 specify that a user may sign the entire form or parts of the form. 692 In addition, multiple users may sign a form. 694 Automatic Actions 696 UFDL supports automatic timed behavior activated by the form. Forms 697 can automatically cancel themselves, submit themselves to a server 698 for processing, open new forms, and upload information to a server. 700 The ability to perform automatic actions provides a mechanism that 701 form designers can use to create stated connections with other 702 applications. An application typically requiring a stated 703 connection is a database management system. 705 Logical Operations and Arithmetic Computations 707 UFDL uses a set of options to describe a form object's appearance 708 and behavior. For example, the option bgcolor describes an object's 709 background color. UFDL permits form designers to use literal values 710 or logically computed values (called computations) to determine the 711 value of an option. 713 These computations are resolved when the form appears. You can nest 714 computations, employ complex mathematical operations, populate and 715 use arrays, and make decisions. 717 Computations provide designers with a very powerful and 718 sophisticated tool for customizing forms to the needs of individual 719 users and applications. It takes very little code (one line per 720 logical computation) and it allows decisions regarding a form's 721 appearance and behavior to occur at run-time. 723 Functions 725 UFDL functions allow forms to perform procedural logicas well as 726 complex operations that would normally require complicated 727 conditional statements. For details, see 7: UFDL Functions". 728 Stand Alone Definitions 730 All aspects of a form's appearance, behavior, and content are 731 integral to the form definition. Therefore, unless you specify 732 otherwise, the entire form definition and the user data travel with 733 the form when a user submits it for processing. Consequently, you 734 can transmit any UFDL form to any site with a UFDL-compliant form 735 viewer application and the viewer will display the form correctly. 737 The only exception to this rule occurs when the form design 738 specifies partial submission of forms. UFDL permits form designers 739 to specify partial submissions in one of two ways: 741 * by specifying which parts to transmit 743 * by specifying HTML format 745 Partial submissions help reduce network traffic and transmission 746 time. 748 Context Sensitive Help 750 UFDL provides a mechanism whereby form designers can define help 751 messages for individual items in the form. Help messages appear in 752 a window overlaying the form. 754 Enclosures 756 Users can enclose external files in UFDL forms. They can organize 757 the files into folders, and they can display, copy, or remove the 758 files. Enclosed files are encoded using the base64 encoding 759 technique. 761 UFDL includes a MIME type with an enclosed file's description. 762 This allows form viewer applications to choose an appropriate 763 viewer (for example, World Wide Web browser, word processor, etc.) 764 when displaying enclosures. 765 ------ 767 2.3 Description of a UFDL Form 768 A UFDL form is a collection of items (for example, buttons, labels, 769 amd fields) organized into pages. There are items to display fixed 770 values, items to collect user input, items to initiate actions, and 771 items to assist with form navigation. The decision about which 772 items to place on a page and how many pages to include in the form 773 is application dependent. 775 UFDL provides a set of options for assigning characteristics to the 776 form and to its pages and items. These include such things as the 777 behavior, appearance, and location of an item. UFDL defines default 778 settings for many of these options, or you can define your own 779 settings in the form. 781 The following example describes a simple two-page form: 782 version = "4.0.0"; 783 bgcolor = ["ivory"]; 785 page_1 = new page 786 { 787 bgcolor = ["seashell"]; 789 next_page_button = new button 790 { 791 value = "Next Page"; 792 url = ["#page_2.global"]; 793 } 794 } 795 page_2 = new page 796 { 797 fontinfo = ["Helvetica", "14", "plain"]; 799 hello_label = new label 800 { 801 value = "Hello, world."; 802 } 803 } 805 For information on the syntax rules of a form description, see 806 "2.4-Syntax of UFDL" 807 ------ 809 2.3a What is a Page? 811 A form page is similar to a page in a paper form. Each page 812 consists of its own set of items. You can place any number and type 813 of items on a page. The number of items, their sizes, and their 814 locations determine the size of the page. 816 See the discussions of 'Relational and Absolute Positioning' 817 and 'Item Placement' for more information on this topic. 819 In some senses, pages act like independent forms. They have their 820 own size, appearance, toolbars, and characteristics. As well, 821 relational positioning of the page's items is based solely on other 822 items on the same page. 824 The following example shows a page containing a label and a button: 825 page_1 = new page 826 { 827 bgcolor = ["seashell"]; 829 hello_label = new label 830 { 831 value = "Hello, world."; 832 fontcolor = ["blue"]; 833 } 834 next_page_button = new button 835 { 836 value = "Next Page"; 837 url = ["#page_2.global"]; 838 } 839 } 841 For more information on the syntax rules of a page description, see 842 '2.4-Syntax of UFDL' 844 Relational and Absolute Positioning 846 UFDL supports two positioning schemes for creating a page image: 847 relational and absolute positioning. In the relational positioning 848 scheme, each item's location depends on the location and size of 849 one or more other items on the page. For example, a field might be 850 below and slightly to the right of a label. A series of buttons 851 might be placed to appear one after the other. 853 In the absolute positioning scheme, each visible item is anchored 854 to a particular coordinate on the page drawn on the computer 855 screen. Each coordinate represents a distance in pixels from the 856 top left corner of the page. In addition, a form designer using 857 absolute positioning can offset items from other items. 859 Absolute positioning is useful for graphic form design programs 860 because it allows users to drag and drop items on a form. It is not 861 a good cross-platform positioning scheme, although when used 862 carefully in conjunction with relational positioning, it can be 863 successful. 865 Relational positioning provides cross-platform compatibility in 866 UFDL form designs, because all visible items are placed relative 867 to each other. Therefore, if any item's size changes because of a 868 change in font size or a dynamically generated value, other items 869 on the form will shift to accommodate it, while maintaining their 870 positions relative to each other. 872 For more information, see '2.4f-Item Placement' 874 Toolbars 876 The toolbar is a separate and fixed area at the top of a page. 877 It functions much like a toolbar in a word processing application. 879 Typically, you place items in the toolbar that you want users to 880 see no matter what portion of the page they are viewing. Toolbars 881 are optional and each page has its own toolbar. 883 The toolbar and the remainder (or body) of the page operate 884 independently of one another. Both are scrollable, and scrolling 885 one does not scroll the other. The toolbar can also have different 886 characteristics than the page body, and relational positioning of 887 toolbar items is based solely on other items on the same toolbar. 888 ------ 890 2.3b What is an Item? 892 Items are the basic elements of a page. Just as paper forms consist 893 of items like lines, boxes, and instructions, UFDL forms consist of 894 items like lines, boxes, text fields, labels, buttons, and so on. 895 There are two categories of items: 897 - external 899 - internal or hidden 901 A page can include both categories of items. 903 See the section 'UFDL Form Items' in section 4.0 904 for a description of each item. 906 External items occupy space on the page. They can be either visible 907 or invisible. Visible items are things users see like labels and 908 buttons. Invisible items are things like spacers that create white 909 space on the form. 911 Internal items are invisible and occupy no space; instead they 912 trigger form actions or store data used by other items. Action and 913 data items are examples of internal items. An action item initiates 914 a transmission, while a data item contains data stored in the form. 916 An instance is a particular occurrence of an 917 item type. For example, a form may have two 918 labels. Each label is an instance of the 919 item type 'label'. 921 Each type of item has default characteristics. For example, all 922 fields will be a certain length and color unless the form developer 923 specifies otherwise. A form developer can modify an item's default 924 characteristics by adding options to its definition. For example, 925 the field described below on the left would have a default 926 appearance of 60 characters long and one row high (as well as 927 having other default characteristics). On the right, the size 928 option added to its description overrides that default size. 930 date_field = new field 931 { 932 } 933 date_field = new field 934 { 935 size = ["20", "1"]; 936 } 937 Field using default characteristics only 938 Modified size overriding the default size 940 There are defaults for most item characteristics. If the defaults 941 meet your requirements, an item definition may include only the 942 instance identifier, a unique item tag. Instance identifiers are 943 mandatory. They are critical to the relational positioning scheme. 944 For that reason, UFDL incorporates the identifier into the syntax 945 of an item definition. 947 An item's definition includes: 948 - An instance identifier (an item tag that uniquely identifies 949 it). 950 - An open brace following the item declaration. 951 - A close brace at the end of the definition (after the options, 952 if there are any). 953 - Optional information giving the item characteristics, including 954 its position on the page, graphical characteristics and size, 955 initial value and edit state, and instructions for handling the 956 item when the form is submitted. Because these characteristics 957 are optional, the lines that specify them are called options. 959 Here is a sample of an item description: 961 date_field = new field 962 { 963 size = ["20", "1"]; 964 label = "Today's Date"; 965 format = ["date", "long"]; 966 value = "*"; 967 itemlocation = [["after", "name_field"]]; 968 } 970 For more information on the syntax rules of an item's description, 971 see '2.4-Syntax of UFDL' 972 ------ 974 2.3c What is an Option? 975 See the section 'UFDL Form Options' in section 976 4.0 for a description of each option. 978 An option defines one characteristic of a form, a page, or an item. 979 There are options to specify each aspect of the appearance and 980 behavior of your form. Some options apply to the entire form, 981 others apply only to items, and still others apply to pages or 982 items. The example below shows options giving characteristics to an 983 entire form, to a page, and to a particular item. 985 version = "3.2.0"; 986 bgcolor = ["ivory"]; 987 page_1 = new page 988 { 989 ... 990 page_1 = new page 991 { 992 bgcolor = ["seashell"]; 994 bar_box = new box 995 { 996 ... 997 bar_box = new box 998 { 999 bgcolor = ["black"]; 1000 size = ["60", "5"]; 1001 } 1002 ... 1004 Options that appear at the top of the form, like the example on the 1005 far left, are called global settings. They apply to the whole form. 1007 Options that appear at the top of a page, like the example in the 1008 center, are called page settings. They apply to the entire page. 1009 Page settings override any similar global settings-but only for the 1010 page on which they occur. 1012 Options within items, like the example on the far right, apply only 1013 to the item whose description they are in. 1014 ------ 1016 2.3d Including External Files 1018 See the '#include' section in section 2.8a for a 1019 description of the '#include' statement. 1021 The UFDL #include statement allows you to include external files in 1022 your form definition much as you would include header files in a 1023 C language source file. The form viewer application replaces the 1024 #include statement with the contents of the file you specify. The 1025 included file must reside in a secure include directory accessible 1026 to the form viewer application. 1027 ------ 1029 2.3e Unrecognized Items and Options 1031 User-Defined Items and Options and Newer UFDL Items and Options 1032 As a UFDL form viewer parses a form, it ignores items and options 1033 it does not recognize. This feature has a number of advantages. 1035 * It allows a form designer to include items and options for new 1036 form viewer applications without affecting the form's behavior 1037 in other viewers. 1039 * Form processing applications can use the custom items and 1040 options when processing the form. One example of a custom item 1041 might be an SQL query item the application uses to populate a 1042 response form. 1044 Unrecognized items and options include: 1046 * User defined (or custom) items and options. 1048 * Items and options from releases of UFDL that are newer than the 1049 user's form viewer application understands. 1050 ----- 1052 2.4 Syntax of UFDL 1054 2.4a Basic Syntax Rules 1056 The basic syntax rules of UFDL are: 1058 * It is case sensitive. 1060 * It ignores white space around and within statements. 1062 * It permits multiple line statements. 1064 * It permits multiple statements per line. 1065 ------ 1067 2.4b Form Definition 1069 The syntax of a UFDL form definition is as follows: 1071 * 1072