XML Forms Architecture (XFA) Specification

XML Forms Architecture (XFA) Specification Contents Preface Intellectual Property Document Contents Intended Audience Perspective Used in Describing Processing Guidelines Associated Schemas Related Documentation Conventions Notational Conventions Typefaces Unicode Character Codes Document Object Model Notation Optional Terms Graphical Conventions Layout Drawing Conventions Part 1: XFA Processing Guidelines Introduction to XML Forms Architecture (XFA) Key Features Scenarios for Using an Interactive Form Described by XFA Interacting with a User Form Appearance Actions the User Can Trigger Accessibility and Field Navigation Printing Forms Processing Machine-Generated Data Family of XFA Grammars Representation of an XFA Form Packaging an XFA Form for Application Interchange XML Data Package (XDP) PDF Document Major Components of an XFA Form: XFA Template and Data XFA Template About XFA Template Containers of Fixed and Variable Content The draw element, a container for fixed data The field element, a container for variable data Containers of Other Containers Laying Out the Containers (and Their Data) to Create the Form’s Appearance Scripted Components of an XFA Template Data Data Binding: Making the Connection Between XFA Template and Data Lifecycle of an XFA Form Creating an XFA Template Filling Out an XFA Form Opening a Form Providing Data to the Form Saving an In-Progress Version of the Form Committing a Form Processing Form Data, a Server Application Task Template Features for Designing Static Forms Form Structural Building Blocks Container Elements Containers Associated with Variable Content Field Exclusion Group Containers of Fixed Content Draw Containers That Group Other Container Elements Template Subform Area Exclusion Group Containers That Represent Physical Surfaces and Regions Content Area Page Area Page Set Types of Layout Elements Content Elements User Interface Basic Composition Measurements Values Units Angles Restrictions Line, Arc, Rectangle and Border Formatting Handedness Handedness of Stroke Elements Handedness of Borders and Rectangles Borders Fill Content Types Text Lines, Rectangles, and Arcs Date, Time, and DateTime Boolean, Integer, Decimal, and Float Absent Content Decimal Point (Radix Separator) Images Background (draw) Images Images Provided as Data Scaling the Image to Fit the Container (aspect) External Data Formatting Text That Appears as Fixed or Variable Content Paragraph and Font Formatting of Fixed and Variable Content Alignment and Justification Line Height Other Formatting Formatting Rich Text for Fixed and Variable Content Rich Text Used for Formatting Rich Text Used to Embed Objects Formatting Variable Content Picture-Clause Formatting in General Locale-Specific Picture Clauses Barcode Formatting of Variable Text Basic Layout The Layout Processor Box Model Area Barcode ContentArea Layout Object Geometric Figure Images PageSet Element PageArea Element Subform Text Size, Margins and Borders of Widgets Size Margins and Borders Size Requirement for Containers Layout Strategies Positioned Layout Forbidden Condition: Negative Coordinates Clipping Locating Containers Based on Data Page Background Rotating Containers Rotating Positioned Content Rotating Flowed Content Transformations Flowing Text Within a Container Text Layout in the Horizontal Direction Text Layout in the Vertical Direction Concealing Container Elements Concealing Containers Concealing Containers Depending on View Exclusion of Hidden Containers in the Data Binding Process Appearance Order (Z-Order) Extending XFA Templates Adding Custom Named and/or Nested Data to a Template (extras) Adding Metadata or Comments to a Template (desc) Object Models in XFA XFA Names Document Object Models General Information Hierarchy of DOMs DOMs and XML Grouping Elements and Whitespace Properties vs. Children Properties Children The DOMs Used in XFA The Configuration DOM The Connection Set DOM The Connection Set Data DOM The Data Description DOM The Form DOM The Layout DOM The Source Set DOM The Template DOM The XFA DOM The XFA Data DOM The XML Data DOM Interaction of the DOMs XML Data DOM and XFA Data DOM Template DOM, XFA Data DOM, and Form DOM Template DOM, Form DOM, and Layout DOM Scripting Object Model About SOM Expressions The Receipt Example SOM Conventions Basic Object References Compound Object Names Shortcuts More on $record Repeated Elements Explicitly Named Objects Transparent Nodes Area Objects Are Always Transparent Variables Objects Are Always Transparent Other Transparent Objects Reference by Class Attributes Internal Properties and Methods Name clashes Selecting Multiple Nodes The Parent Property Selecting Descendants At Any Level SOM Expressions That Include Periods and Dashes SOM only Mixed SOM/script context Using SOM Expressions in FormCalc Runtime resolution of object names Using SOM Expressions in ECMAScript Obtaining the value of an expression SOM expressions that use special characters Using SOM Expressions in Bind References Relative References The Current Container Unqualified References to Children of the Container Unqualified References to Siblings of the Container Unqualified References to Ancestors of the Container Differences Between Qualified and Unqualified References "$." Versus Unqualified SOM Expressions Inferred Index Inferred Index for Ancestors of the Container Relative Index SOM Expressions That Reference Variables Properties Exchanging Data Between an External Application and a Basic XFA Form Creating, Updating, and Unloading a Basic XFA Data DOM Background and Goals XFA Data DOM Basic Concepts About the XFA Data DOM dataValue Nodes dataGroup Nodes Relationship Between the XFA Data DOM and the XML Data DOM Tree Notation Default Data Mapping Rules Document Range XML Logical Structures Start Element Namespaces Record Elements Data Value Elements Data Values Containing Character Data Data Values Containing Mixed Content Data Values Containing Empty Elements Data Values Representing Null Data Null Data in Mixed Content Data Values Containing Element Content Data Group Elements Attributes White Space Handling White Space in Data Groups White Space in Data Values Rich Text Image Data Updating the XML Data DOM for Changes Made to the XFA Data DOM Updating the XFA Data DOM for Changes Made to the XML Data DOM (Append Loading) Unload Processing Unloading Node Type Information Unloading Null Data Logical Equivalence Localization and Canonicalization Requirements for Localization Satisfying Locale-Dependent User Expectations Specifying the Locale to Use During Localization and Canonicalization About the Canonical Format Used in the Data and Form DOMs About Picture Clauses Limitations in Picture Clauses Recommendation on Specifying Locale Selecting Between Alternate Picture Clauses Dataflow Paths for Localizing and Canonicalizing Data Rules for Localizing Data The localeSet Element Calendar symbols Date and time symbols Date patterns Time patterns Currency symbols Number symbols Loading a Template to Produce the XFA Template DOM Creating an XML Template DOM Creating an XFA Template DOM Supporting Template-Creator Stamps Basic Data Binding to Produce the XFA Form DOM About Data Binding Conventions Principles of Data Binding The Bind Element The match property The picture property The ref property Simple Example of Data Binding Data Binding Steps Create Form Nodes and Match with Data Nodes (Steps 1 and 2) Forms with Non-Unique Names Content Type Transparent Nodes Exclusion Groups Choice Lists That Can Have Multiple Values Explicit Data References Match Attributes (Step 3) Re-Normalization (Step 4) Calculations and Validations (Step 5) Form Ready Event (Step 6) Remerge and Incremental Merge (Step 7) Form Processing Data Output Representing and Processing Rich Text About Rich Text Rich Text Used for Formatting Rich Text That Inserts External Objects Version Identifiers for Rich Text Producers and Rich Text Specifications Representation of Rich Text Across XML and XFA DOMs Recognizing Rich Text Recognizing Data as Rich Text Recognizing Rich Text Introduced in the Template Representing Rich Text in the XFA Data DOM Converting Rich Text into Plain Text Properties of XFA Data DOM Objects That Represent Converted Rich Text Properties of XFA Template DOM Objects That Represent Converted Rich Text Providing Rich Text Data Through a User Interface Updating the XML Data DOM Rich Text That Contains External Objects Displaying and Printing Rich Text Template Features for Designing Forms with Repeating Sections Prototypes Defining Prototypes Referencing Prototypes Overriding Prototype Properties Overriding Attributes Overriding Data Content Overriding Child Elements Forms with Repeated Fields or Subforms Repeated Subform Declarations Fixed Occurrence Numbers Record Mode Globals Data Window Layout for Repeating Sections Break Conditions Layout for Growable Objects Background and Goals Growable Containers Growth and the Box Model Growth in Growable Positioned Objects Text Placement in Growable Containers Text Layout with Growable Width Text Layout with Growable Height Flowing Layout for Containers Top-to-Bottom Layout Left-to-Right Top-to-Bottom Tiled Layout Interaction Between Growable Objects and Flowed Content Non-Interactive Form Layout Interactive Form Fill-In Effect of Container Rotation on Flowed Layout The Layout DOM The Layout Algorithm Error Handling Content Overflow Content Splitting Split Restrictions Splitting a Container Having Child Containers Borders and Splitting Flowing Between ContentArea Objects Maximum Occurrence Limits Minimum Occurrence Limits Adhesion Leaders and Trailers Bookend Leaders and Trailers Overflow Leaders and Trailers Leader/Trailer Lists Inheritance of Overflow Leaders and Trailers Combined Leaders and Trailers Tables Dynamic Forms Static Forms Versus Dynamic Forms Data Binding for Dynamic Forms Variable Number of Subforms The Occur Element The initial property The max property The min property Blank Form Greedy Matching Globals Explicit Data References Subform Set Instance Manager Layout for Dynamic Forms Adhesion in Dynamic Forms Break Conditions for Dynamic Forms Break on Entry Break to Empty pageArea or contentArea Combining startNew with beforeTarget Break on Overflow Combining Overflow with Other break Properties Combined Break Condition and Occurrence Limits Combining Break and Maximum Occurrence Combined Break and Minimum Occurrence Automation Objects How Script Elements Are Used Within Automation Objects Document Variables Variables Used to Hold Boilerplate or Image References Variables Used to Define Named Script Objects Instantiation of Named Script Objects Declaring and Referencing Named Script Objects Calculations About Activation Result Validations About As compared to UI validation As compared to XML validation Types of Validation Tests Activation Initialization Interactive Non-Interactive User Interactions With Validation Tests Error and Warning Messages Interacting with the User to Obtain a Valid Value Responding to Test Failures nullTest Datatype test formatTest scriptTest Events Application Events DOM Events Subform Events Exclusion Group Events Field Events Connection Events Properties $event properties Order of Precedence When Multiple Actions Are Defined for an Event Order of Precedence for Automation Objects Activated by the Same Trigger Scripting Purpose of Scripting Specifying Where to Execute a Script Applications of the runAt="both" property Selecting a Script Language Setting Up a Scripting Environment Exception handling Picture Clauses and Localization Naked References in JavaScript Unicode Support Forms That Initiate Interactions with Servers Submitting Data and Other Form Content to a Server About Content Interchange Client Submit Event That Does Not Expect Returned Data Example of an event that does not expect data to be returned from the server Client Submit Event That Processes Data at the Server Client-side actions Server-side actions initiated by above Client Submit Event That Conditionally Processes Data at the Server Using Web Services to Communicate Between XFA Processing Applications and Other Systems Web Service Architecture Cycle of Operation in a Web Service Transaction Structure of a Web Service Message Example That Illustrates the Web Services Architecture Input message queries server for the trading price of a corporation Output message provides trading price (if successful) or a status indicator (if not successful) Definition file may define multiple individual operations, each using a different connection set Messages Represented in the Connection Data DOM Associating Fields and Exclusion Groups with Nodes in the Connection Data DOM Data Conditionally Copied Between the Data DOM and the Connection Data DOM Replying to the Web Server and Error Responses Schema and WSDL Invoking ADO APIs Through the Source Set DOM The Source Set Document The sourceSet element The source element The connect element The connectString element The user and password elements The command element The query element The recordSet Element The select element The map element The bind element Template features used with the Source Set DOM Fields bound to columns in the data base The push buttons Updates and rollbacks Null handling User Experience Widgets Barcode Widget Button Check Box and Check Button Check Buttons Not Contained in an Exclusion Group Check Buttons Contained in an Exclusion Group Choice List Choice List Before Interacting with User User Selects Field Whether the User May Select Multiple Data Values Whether the User May Provide Data Values User Exits Field Data Associated with Choice List Selections When to Update the XFA Data DOM Date/Time Editing Widget User Selects a Field That Has Date-Time Edit Widget User Supplies Data to the Field User De-Selects the Field Default UI External Object Widget Image Edit Widget Numeric Edit User Selects a Field That Has a Numeric Edit Widget User Supplies Data User De-Selects the Field Password Edit Widget Signature Widget User in an Interactive Context Clicks on a Signature Widget User in an Interactive Context Changes Signed Data User in a Non-Interactive Context Signs a Printed Form Text Edit Widget User Selects a Field That Has a Text Editing Widget User Supplies Data User De-Selects the Field User Experience with Digital Signatures Signature Event Produces an XML Digital Signature Signature Widget Produces a PDF Signature Accessibility and Field Navigation Traversal: Tabbing Order and Speech Order Explicitly Defined Keystroke-Initiated Traversals Default Keystroke-Initiated Traversal Non-Keystroke Traversals Traversal Initiated When Maximum Number of Characters Supplied Traversal When Speech Application Completes the Current Container Traversal Sequences That Support Speech Delegating Focus to Another Container Accelerator Keys: Using Keyboard Sequences to Navigate Speech of Text Associated with a Container Other Accessibility-Related Features Dealing with Data in Different XML Formats Extended Mapping Rules Document Range Transforms The attributes Element Data Group Elements with Attributes Data Value Elements with Attributes Null Values with Attributes The excludeNS Element The groupParent Element The ifEmpty Element The nameAttr Element The picture Element The presence Element The range Element The record Element The rename Element The startNode Element The whitespace Element The xfa:dataNode Attribute XSLT Transformations XSLT Preprocessing XSLT Postprocessing Security, Control, and Digital Signatures Tracking and Controlling Templates Through Unique Identifiers Unique Identifiers and Time Stamps Processing Requirements for Template Designing Applications Processing Requirements for XFA Processing Applications Respecting External References in Image Data and Rich Text Discarding Unexpected Submitted Packets Signed Forms Types of Digital Signatures Using Digital Signatures to Achieve Different Levels of Security Differences Between XML and PDF Digital Signatures Using certified signatures to restrict changes What part of the document can be signed Tracking changes during a form’s lifetime Refresher on the Relationship Between XFA and PDF Integrity Using XML digital signatures for integrity Using PDF Digital signatures for integrity Authenticity Using XML digital signatures for authenticity Using PDF Digital signatures for authenticity Non- Repudiability Usage Rights Signatures (Ubiquitized Documents) XML Digital Signatures Signing a Form Removing a Signature Verifying a Signature Template Provides Instructions on Signature Operation Signature filter: Handler, algorithms, and certificates to use to produce a signature Manifest: Data and other content digested by the signature handler Signature destination XFA-Specific Information in the XML Digital Signature Example PDF Signatures Part 2: XFA Grammar Specifications Template Specification Guide to the Template Specification How to Read an Element Specification Properties Regular Properties One-of Properties Property Defaults Children Element Occurrence Singly Occurring Elements Multiply Occurring Elements Template Reference The arc element The circular property The edge property The fill property The hand property The id property The startAngle property The sweepAngle property The use property The area element The area child The colSpan property The desc property The draw child The exclGroup child The exObject child The extras property The field child The id property The name property The relevant property The subform child The subformSet child The use property The x property The y property The assist element The role property The speak property The toolTip property The barcode element The checksum property The dataColumnCount property The dataLength property The dataPrep property The dataRowCount property The endChar property The errorCorrectionLevel property The extras property The id property The moduleHeight property The moduleWidth property The printCheckDigit property The rowColumnRatio property The startChar property The textLocation property The truncate property The type property The use property The wideNarrowRatio property The bind element The match property The picture property The ref property The boolean element Content The id property The name property The use property The border element The break property The corner property The edge property The extras property The fill property The hand property The id property The margin property The presence property The relevant property The use property The break element The after property The afterTarget property The before property The beforeTarget property The bookendLeader property The bookendTrailer property The extras property The id property The overflowLeader property The overflowTarget property The overflowTrailer property The startNew property The use property The button element The extras property The id property The use property The calculate element The extras property The id property The message property The override property The script property The use property The caption element The extras property The font property The id property The margin property The para property The placement property The presence property The reserve property The use property The value property The certificate element Content The id property The name property The use property The certificates element The id property The issuers property The oids property The signing property The url property The use property The checkButton element The border property The extras property The id property The margin property The shape property The size property The use property The choiceList element The border property The commitOn property The extras property The id property The margin property The open property The textEntry property The use property The color element The cSpace property The extras property The id property The use property The value property The connect element The connection property The picture property The ref property The usage property The contentArea element The desc property The extras property The h property The id property The name property The relevant property The use property The w property The x property The y property The corner element The color property The extras property The id property The inverted property The join property The presence property The radius property The stroke property The thickness property The use property The date element Content The id property The name property The use property The dateTime element Content The id property The name property The use property The dateTimeEdit element The border property The extras property The id property The margin property The use property The decimal element Content The fracDigits property The id property The leadDigits property The name property The use property The defaultUi element The extras property The id property The use property The desc element The boolean child The date child The dateTime child The decimal child The exData child The float child The id property The image child The integer child The text child The time child The use property The draw element The anchorType property The assist property The border property The caption property The colSpan property The desc property The extras property The font property The h property The hAlign property The id property The margin property The maxH property The maxW property The minH property The minW property The name property The para property The presence property The relevant property The rotate property The traversal property The ui property The use property The vAlign property The value property The w property The x property The y property The edge element The cap property The color property The extras property The id property The presence property The stroke property The thickness property The use property The event element The activity property The execute property The extras property The id property The name property The ref property The script property The signData property The submit property The use property The exclGroup element The access property The accessKey property The anchorType property The assist property The bind property The border property The calculate property The caption property The colSpan property The connect child The desc property The event child The extras property The field child The h property The hAlign property The id property The layout property The margin property The maxH property The maxW property The minH property The minW property The name property The para property The presence property The relevant property The transient property The traversal property The use property The validate property The vAlign property The w property The x property The y property The exData element Content The contentType property The href property The id property The maxLength property The name property The transferEncoding property The use property The execute element The connection property The executeType property The id property The runAt property The use property The exObject element The archive property The boolean child The classId property The codeBase property The codeType property The date child The dateTime child The decimal child The exData child The exObject child The extras property The float child The id property The image child The integer child The name property The text child The time child The use property The extras element The boolean child The date child The dateTime child The decimal child The exData child The extras child The float child The id property The image child The integer child The name property The text child The time child The use property The field element The access property The accessKey property The anchorType property The assist property The bind property The border property The calculate property The caption property The colSpan property The connect child The desc property The event child The extras property The font property The format property The h property The hAlign property The id property The items child The locale property The margin property The maxH property The maxW property The minH property The minW property The name property The para property The presence property The relevant property The rotate property The traversal property The ui property The use property The validate property The vAlign property The value property The w property The x property The y property The fill element The color property The extras child The id property The linear property The pattern property The presence property The radial property The solid property The stipple property The use property The filter element The certificates property The handler property The id property The name property The reasons property The use property The float element Content The id property The name property The use property The font element The baselineShift property The extras child The fill property The id property The lineThrough property The lineThroughPeriod property The overline property The overlinePeriod property The posture property The size property The typeface property The underline property The underlinePeriod property The use property The weight property The format element The extras property The id property The picture property The use property The handler element Content The id property The type property The use property The version property The image element Content The aspect property The contentType property The href property The id property The name property The transferEncoding property The use property The imageEdit element The border property The data property The extras property The id property The margin property The use property The integer element Content The id property The name property The use property The issuers element The certificate child The id property The type property The use property The items element The boolean child The date child The dateTime child The decimal child The exData child The float child The id property The image child The integer child The name property The presence property The ref property The save property The text child The time child The use property The keep element The extras property The id property The intact property The next property The previous property The use property The line element The edge property The hand property The id property The slope property The use property The linear element The color property The extras property The id property The type property The use property The manifest element The id property The ref child The use property The margin element The bottomInset property The extras property The id property The leftInset property The rightInset property The topInset property The use property The medium element The id property The imagingBBox property The long property The orientation property The short property The stock property The trayIn property The trayOut property The use property The message element The id property The text child The use property The numericEdit element The border property The extras property The id property The margin property The use property The occur element The extras property The initial property The max property The min property The oid element Content The id property The name property The use property The oids element The id property The oid child The type property The use property The pageArea element The area child The blank property The contentArea child The desc property The draw child The exclGroup child The extras property The field child The id property The initialNumber property The medium property The name property The numbered property The occur property The relevant property The subform child The use property The pageSet element The extras property The id property The name property The occur property The pageArea child The pageSet child The relevant property The use property The para element The hAlign property The id property The lineHeight property The marginLeft property The marginRight property The preserve property The radixOffset property The spaceAbove property The spaceBelow property The tabDefault property The tabStops property The textIndent property The use property The vAlign property The passwordEdit element The border property The extras property The id property The margin property The passwordChar property The use property The pattern element The color property The extras property The id property The type property The use property The picture element Content The id property The use property The proto element The arc child The area child The assist child The barcode child The boolean child The border child The break child The button child The calculate child The caption child The certificate child The certificates child The checkButton child The choiceList child The color child The connect child The contentArea child The corner child The date child The dateTime child The dateTimeEdit child The decimal child The defaultUi child The desc child The draw child The edge child The event child The exclGroup child The exData child The execute child The exObject child The extras child The field child The fill child The filter child The float child The font child The format child The handler child The image child The imageEdit child The integer child The issuers child The items child The keep child The line child The linear child The manifest child The margin child The medium child The message child The numericEdit child The occur child The oid child The oids child The pageArea child The pageSet child The para child The passwordEdit child The pattern child The picture child The radial child The reason child The reasons child The rectangle child The ref child The script child The signature child The signatureProperties child The signData child The signing child The solid child The speak child The stipple child The subform child The su