[This local archive copy is from the official and canonical URL, http://www.w3.org/1999/05/XFA/xfa-template-19990614; please refer to the canonical source document if possible.]
© Copyright 1999, JetForm Corporation. All rights reserved.
This document is a Submission to W3C from JetForm Corporation.
This document, as part of a family of specifications referred to as the XML Forms Architecture, describes an XML based language, XFA-Template, for modelling electronic form templates. XFA provides for the specific needs of electronic forms and the applications that use them. XFA addresses the needs of organizations to securely capture, present, move, process, output and print information associated with electronic forms. This document specifically describes the open and extensible construction of secure forms with high fidelity composition, automated calculation and validation, pluggable user-interface components, and flexible data handling.
In order to provide an understanding of what an electronic form is, this section provides some background information.
Most people are consumers of forms, rather than producers or designers of forms. Yet, in order for a software product to utilize forms, someone first had to expend a degree of thought and work towards the act of creating a form. This specification is focused on the task of form creation, and it is important to distinguish between the 'form' that the creator designs, and the 'form' that a consumer handles -- they both represent the same form, but at two very different stages in the form's life-cycle.
This subsection introduces key XFA concepts and terminology. The following subsection, Form Structure, expands on these concepts in the context of the structure of the form.
Anyone that has used a traditional paper form as a consumer has a very clear impression of what a "form" is. There is little thought given to the distinction between a blank form, and a form which has been completed. On the other hand, a form designer is concerned only with the creation of blank forms. Therefore, XFA clearly distinguishes between the two stages via the following terminology, as detailed in subsequent sections.
Consider the following diagram:
 |
|
Diagram FORM-1 -- An example of a form
|
This is an example of a form. To an end user (form consumer), it represents something to be filled out, by entering data into the white spaces. There is little or no distinction between a blank form and a filled one, other than the presence of data. In fact, the absence of data in a particular data entry element can be as meaningful as the presence of data.
In contrast, a form designer views it as a vehicle for capturing, rendering and manipulating data. As such, the designer is concerned with issues of layout, interaction and processing. A template is a specification of capture, rendering and manipulation rules that will apply to all form instances created from that template.
A form is the result of combining a form template with data. This includes the initial case of a blank form which is a form template with an empty data set. The formal definition is:
"A form is the combination of a template and state (data)."
An end-user (form consumer) interacts with a form, typically for one of the following reasons:
When selecting a form to be filled interactively, the user perceives that s/he is selecting a 'blank' form. The user is performing an operation similar to starting a new document in a word processor, by first selecting a template. The user selects this template that the form-filling application uses to construct a 'form', which at first appears blank.
The user may fill out the form, and save the data content to a file or a database. It is important to note that the data was saved, not the form (and certainly not the template). Some time later, the user either:
There are also cases where the entire state of the form (data and template) need to be saved together, and that capability is also supported by this specification.
As described in the previous section, a template represents the potential for a form. The formal definition is:
"A Template is a collection of related subforms and processing rules."
A form designer interacts with the form template for one of the following reasons:
For more information, please see how a template participates in form structure, or the syntax description of the <Template> element.
This specification uses the term Content to refer to any piece of data that may appear on a form. Content includes, but is not necessarily limited to:
The end user, while very aware of a form's interactive content, generally doesn't make a distinction between that content and the field that houses it. However, the distinction is important to the form designer. Content elements tend to be concerned with data related issues (e.g., data type and limitations), while field elements are concerned with presentation and interaction.
For more information, please see the form structure description of content, or the syntax description of the various content elements.
The term Container or Container Object refers to an element that houses a piece of content. The container is concerned with all form-related aspects of dealing with its content, for example:
For more information, please see the description of containers under Form Structure or syntax descriptions of the container elements.
A field is a container element that houses one piece of dynamic content of a form. As instances of forms are created from a common template, the static content is generally the same across those instances. However, the dynamic content is very likely to change from instance to instance.
The end user filling out a form effects change to dynamic content. Often, the user interacts with a field via data entry (typing). However, every interactive element on a form is a field. So, pushbuttons, check-boxes, and even some images are also fields.
The end user is not the only source of change to dynamic content. Applications, database input, dynamic calculations and many other sources can also change this content.
In diagram FORM-1, call-outs indicate a few of the many fields. Note the push-button in the lower-right corner is also a field.
For more information, please see how a field participates in form structure, or the syntax description of the <Field> element.
This section describes the most significant XFA objects and their relationships.
The content within a form template is presented to the user by enclosing the content within container objects. Containers determine the layout and formatting of the form content and include the Field element introduced above, as well as the Draw, Area, Subform and Exclusion Group elements. This specification describes a variety of containers that vary in terms of their behavior and the types of objects that they can enclose.
Forms invariably contain static content. This content, often referred to as boilerplate, typically provides context and assistance for consumers of the form. A Draw element encloses each piece of static content. A user cannot directly interact with a Draw object. Refer to the diagram FORM-1 for some examples of Draw elements. Note that call-outs indicate only two of the many draw elements on the form. Note also that Draw element content is not limited to text. For example, a Line element is legitimate content for a Draw element.
The following is an example of a Draw element that will produce the outline of a rectangle with the dimensions of one-inch square, positioned at an (x,y) coordinate of (0,0):
<Draw X="0" Y="0" W="1in" H="1in"> <Value> <Rectangle/> </Value> </Draw>
For more information, please see the syntax description of the <Draw> element.
A Field object is the workhorse of a template, and represents a data-entry region. A user is typically expected to interact with the fields by providing data input. Fields provide a pluggable user interface and support for a broad variety of content data-typing.
The following is an example of a Field element that will produce a one-inch wide data-entry region capable of accepting textual input, positioned at an (x,y) coordinate of (0,0):
<Field Name="ModelNo" X="0" Y="0" W="1in" H="12pt"/>
For more information, please see the syntax description of the <Field> element.
An Area is a grouping of form container objects. The grouping itself is not visible, although the objects themselves may be visible.. For example, in diagram FORM-1, the vendor name and address data entry elements, along with the corresponding static text elements might be grouped into an area. Areas provide the designer with a means of organizing elements on a form, so that they may be moved or manipulated as a whole.
An area is itself a container.
The following is an example of an Area element that encloses two text fields:
<Area> <Field Name="ModelNo" X="0" Y="0" W="1in" H="12pt"/> <Field Name="SerialNo" X="0" Y="16pt" W="1in" H="12pt"/> </Area>
For more information, please see the syntax description of the <Area> element.
Common paper forms often contain sections and subsections that are easily distinguished from one another. For example, there are three distinct sections for header, detail and summary information in diagram FORM-1 above. The form is really a collection of these sections and subsections, each of which XFA refers to as a subform. One can think of a subform as a sort of interactive Area. Some of the features offered by Subforms include:
The subform likely provides the level of granularity that a form object library would use. A form object library is a tool used by form designers to store commonly used groupings of form container objects, for example, company letterhead.
The following is an example of a Subform element that encloses two one-inch square text fields:
<Subform> <Field Name="ModelNo" X="0" Y="0" W="1in" H="12pt"/> <Field Name="SerialNo" X="0" Y="16pt" W="1in" H="12pt"/> </Subform>
For more information, please see the syntax description of the <Subform> element.
An Exclusion Group is a non-geographical grouping of objects. By grouping the objects together, they exhibit mutual exclusivity semantics commonly associated within radio-buttons or ballot/check-boxes; only one of the objects is permitted to have a value or be selected by the user.
This specification extends the functionality of mutual-exclusion to any type of field object, not just radio-buttons/check-boxes as is typical of most electronic forms.
<ExclGroup> <Field Name="Agree" X="0" Y="0" W="1in" H="12pt"> <UI><CheckButton/></UI> </Field> <Field Name="Disagree" X="0" Y="12pt" W="1in" H="12pt"> <UI><CheckButton/></UI> </Field> </ExclGroup>
For more information, please see the syntax description of the <ExclGroup> element.
A Template is a non-geographical grouping of objects. The template represents the form design as a whole, enclosing all of the objects and intelligence of the form.
The following is an example of a Template element that describes a form comprised of two one-inch square text fields:
<Template> <Subform> <Field Name="ModelNo" X="0" Y="0" W="1in" H="12pt"/> <Field Name="SerialNo" X="0" Y="16pt" W="1in" H="12pt"/> </Subform> </Template>
Every container has the notion of a value. This value can be used in calculations and may be persisted when the form's data is saved. For Draw and Field containers, the value is the container's content, available through the <Value> subelement. For containers of containers (Area, Exclusion Group and Subform), the value of the container is the value of one of the child containers. The rules for determining which child container's value to use are described with each container element, in the section Major Elements.
Note that the container value is more than a read-only property. There are operations that can set a container's value, even if the container is a container of other containers.
A form is composed of objects that the user perceives as the form content, such as the graphical and textual content that is part of the static form design, and the content present in the fields typically provided by a user. These content objects are arranged within the template coordinate space and presented to the user by enclosing the content within container objects such as Draw, Field, Area, or Subform container objects.
Content is available in a variety of types. The following is the list of content types described by this specification:
It should be recognized that not all types of content are appropriate everywhere on a form. Specifically, while it may be possible for all of the content types to be rendered on the form, it is likely that user will have a restricted set of content types that s/he may use for data input into the form. This is explained in the following two sections.
Draw content refers to the set of possible content elements that can all be enclosed inside a draw object, and this corresponds to the entire set of content types. Thus, while practically all content objects can be presented or 'drawn', a form filling application may not be capable of providing a method for the user to input all types of content objects.
For example, a typical form will have textual content presented on the form itself (providing field labels and instructional text to the user) and permit the user to input textual content into the fields of the form. Another draw content type presented on forms includes rectangles and lines that provide the graphical composition, but the user would not typically have the ability to input a line or a rectangle into a field on the form.
Field content is the subset of the available content types that a user can input with a form filling application and may be enclosed inside a field object. The majority of form field content is textual or numeric data.
This specification specifies the following subset of content objects as the minimum that a form filling application should permit within a field container:
Null values have a traditional significance with databases, where it is important to have a means to explicitly signify the lack of a value. A database table column in may be permitted to hold null values, and this is used in the screen-based data entry forms and subsequent queries as a means of identifying or excluding the table columns that have no value. It is common to construct a query that selects database table rows where one or more criteria are not null.
This requirement and subsequent usage of null values also applies to electronic forms, where it is often important to distinguish fields that have no value, and exclude these same fields from calculations. For instance, imagine a form that accepts up to ten numbers and calculates the average. The form has ten entry fields, and one calculated displayed average field. The user is not required to provide ten numbers; s/he can provide as few or many numbers up to a maximum of ten. The correct calculation of the average is dependent upon excluding the empty fields from the average. Were all ten fields included in the average calculation, including the empty fields, the average could be skewed by accidentally considering empty fields to have a value of zero. In this example it is important that there be a straightforward way for distinguishing between null (empty) fields, and fields where the user has explicitly typed a value including a possible zero value.
All content elements are capable of holding a value of null. This is, by default,
the value of an empty content element. A content element can explicitly hold
a value of null by enclosing the <Null/>
element.
Therefore, the following two elements have the equivalent value:
<Integer/>
and
<Integer><Null/></Integer>
However, the following two elements have different values; the first has a value of null, and the second has a value of zero:
<Integer/>
versus
<Integer>0</Integer>
Content elements also have an attribute NullIfEmpty that permits
this behavior to be changed. As previously described, empty content elements
are null by default -- adjusting this attribute will require that null values
be explicitly specified with a <Null/>
element.
Note that with text content, there is a distinction between null content and empty content. In particular, the following two elements are equivalent:
<Text NullIfEmpty='1'></Text> <Text NullIfEmpty='1'><Null></Text>
However, these are not the same as the following, which represents an empty string, as opposed to null content:
<Text NullIfEmpty='0'></Text>
In general, processing applications deal with null content in ways that are intuitive to the end user. For example, a text field that contains null content and a text field that contains an empty string will often be treated as being identical, unless the form designer explicitly wants to take advantage of null content.
This specification makes a clear distinction between the content of a container and the user interface (UI) required to render that content and provide interaction. While there often is a relationship between content and UI (e.g., date content would normally be captured with a date-oriented UI), the separation allows both the application and the form designer some degree of flexibility in choosing the right UI. This separation was motivated by the following three requirements:
For more information, please see the syntax descriptions of the user interface elements.
Each container may have a <UI>
subelement for specifying user interface for the container. That <UI>
element, in turn, can contain zero or more child elements, each of which specifies
a possible user interface for the container. If the <UI>
element contains no children or is not present, the application chooses a default
user interface for the container, based on the type of the container's content.
If the <UI> element contains
one or more subelements, the application chooses the the most appropriate one,
based on what is available to the application. Note that the order of child
elements does not bias the application's selection. Occasionally, none of the
listed user interfaces will be available. In such a case, the application chooses
a default, based on the content type.
The form designer can specify a third-party user interface by including an
<ExObject>
element as a child of the <UI>
element. The <ExObject> element
includes attributes which specify the nature of the third-party interface.
If an application supports third-party interfaces and the user interface specified
in the <ExObject> element is
available, the application may choose that interface. If not, it will choose
one of the other interfaces specified. Again, if none of the specified interfaces
is appropriate, the application will choose a default based on the content type.
When developing internationalized applications, a locale is the standard term used to identify a particular nation (language and/or country). A locale defines (but is not limited to) the format of dates, times, numeric and currency punctuation that are culturally relevant to a specific nation. A properly internationalized application will always rely on the locale to supply it with the format of dates, and times. This way, users operating in their locale will always be presented with the date and time formats they are accustomed to.
A locale is identified by a language code and/or a country code. Usually, both elements of a locale are important. For example, the names of weekdays and months in English Canada and in the UK are formatted identically, but dates are formatted differently. So, specifying an English language locale would not suffice. Conversely, specifying only a country as the locale may not suffice either -- for example, Canada, has different date formats for English and French.
A locale identifier is a unique string representing a locale. The structure and meaning of locale identifiers are defined in [RFC1766].
In general, every application operates in an environment where a locale is present; this is the ambient locale. In the rare circumstance where the application is operating on a system or within an environment where a locale is not present, the ambient locale will default to English United States (en-US); this is the default locale.
This section describes the most common aspects of how objects are arranged and presented on the presentation medium.
Templates are composed in a space that has maps directly to the real world; the location and size of objects are expressed in real-world units such as inches and centimeters. There is no provision for addressing the device space of a display or print device directly in device units.
The origin of the template modeling space is located at the top-left corner, and the x and y coordinates increase in value towards the bottom-right.
This specification refers to the means of expressing coordinates and dimensional information as measurements.
All measurements are comprised of two components:
The following is an example of several different Font elements with the equivalent Font size expressed in a variety of different measurements.
<Font Typeface="Helvetica" Size="72pt"/> <Font Typeface="Helvetica" Size="1in"/> <Font Typeface="Helvetica" Size="72"/>
All measurements have a quantity or value, which is expressed in a particular unit that may either be explicitly stated or implied.
Common uses of measurements include the description of a length or width of an object, the position of an object, or an offset from a coordinate.
The format of a measurement is:
The following are examples of measurement and their interpretations:
1in -- one inch-5.5cm -- minus five and a half centimeters30pt -- thirty points0 -- a measurement of zero with the unit omittedAll measurements are expressed in a particular unit which may
be specified as a suffix to the value. The unit is known by a short textual
identifier, such as "in" for inches. The default unit
is assumed to be points. For example, the following measurements are equal:
There are two categories of units:
The following list is the set of allowable units and the corresponding identifiers:
Note that a unit specification is not required or implied when the measurement value is zero. Not all elements may support all possible types of units, see the section "Restrictions" below for more detail.
Certain measurements requires the specification of an angle. Angles are always specified in degrees and are measured counterclockwise from a line parallel to the X axis.
Individual elements may place restrictions on measurements; in these cases the corresponding specification of the element will clearly describe the restrictions -- if no restriction is noted, then it shall be assumed that the element does not exhibit any restrictions on measurements.
For instance, the specification for an element may:
Every object that has a visual presence on a form presents itself through a rectangular region, or box, that describes the appearance of the object. This mechanism is known as the box model. All container objects conform to this model.
The box model describes a rectangular region with the following characteristics:
The following diagram illustrates the box characteristics of an object; this particular example shows a box with margins and a border surrounding a gray ellipse content:
 |
|
Diagram BOX-1 -- Box model
|
Every container object has a nominal extent rectangle.
In a GUI-based graphical form designer application, the designer typically defines the nominal extents of positioned objects by using a pointing device to define a rectangular region, such as defining the rectangular region for a field object.
Margins independently inset the container's content and border from its nominal extent. The specification of independent top, left, bottom and right margin values permit the insets to vary with each side of the box. Negative margins are reserved for future use.
Margins can be omitted or explicitly set to zero.
The application of margins to a nominal extent results in a rectangular nominal content region, which displays the container's content. The particular type of enclosed content may also permit the specification of additional margining within the content region; this is referred to as content margins and is distinct from this description of box model margins.
The Nominal Content Region is the rectangular area left over after margins have been applied to a container object's nominal extent. This is the space normally reserved for display of and interaction with the container object's content. Note that the caption may occupy part of the nominal content region.
The box model has an optional mechanism, known as borders, for rendering a rectangle around the content. Independent control over the appearance of sides and corners of the rectangle is provided.
The border has its own insets, independent of the content's margins. This means that it is, in fact, possible to create an object whose border is located graphically within the nominal content region. However, the content shall always have rendering precedence over the border, as described in the section Z-Order.
A border is comprised of one or more optional:
<Edge><Corner>The border is rendered, starting at the top-left corner and proceeding clockwise, with the rendering algorithm being applied for all edges. The direction of rendering is important for the notion of handedness.
The border can also include a fill specification, indicating that the area enclosed by the border is to be filled with some sort of pattern or other shading.
In this specification, a container object is located relative to the its anchor point (typically the container's top-left corner) of the enclosing container's content region. This form of location is referred to as positioning. Content, on the other hand, is located in its container in a manner similar to how text is flowed within a word processing application. This is referred to as flowing.
A future version of this specification may relax the rule that containers are positioned and content is flowed. It may eventually be possible for containers to be flowed within their parents or for a content object to be positioned within its container.
Consider the following example and diagram. It includes a subform that:
|
|
Diagram CONTAINER-1 -- The relationship between
content and containers
|
Note that the small gray circles represent the anchor point positions of the objects, and are purely illustrative -- they would not appear in the actual rendered form. Also note that nominal extents are indicated by broken lines. Again, these are purely illustrative and are not part of the rendering of the form.
The XFA syntax for the example might appear as follows:
<Subform X="0" Y="0" W="3in" H="2in"> <Border> <Margin TopInset=".1in" RightInset=".1in"
BottomInset=".1in" LeftInset=".1in"/>
<Edge Thickness="6pt">
<Color Value="0,0,255"/>
</Edge>
</Border>
<Draw X=".5in" Y=".5in" W="1in" H=".5in">
<Border> <Margin TopInset=".05in" RightInset=".05in"
BottomInset=".05in" LeftInset=".05in"/>
<Edge Thickness="3pt">
<Color Value="0,128,0"/>
</Edge>
</Border>
<Margin TopInset=".1in" RightInset=".1in"
BottomInset=".1in" LeftInset=".1in"/>
<Align HAlign="Left" VAlign="Top"/>
<Value> <Text>XFA Forms Architecture</Text>
</Value> </Draw>
<Draw X="2.7in" Y="1.2in" W="1in" H=".5in">
<Border> <Margin TopInset=".05in" RightInset=".05in"
BottomInset=".05in" LeftInset=".05in"/>
<Edge Thickness="3pt">
<Color Value="0,128,0"/>
</Edge>
</Border>
<Margin TopInset=".1in" RightInset=".1in"
BottomInset=".1in" LeftInset=".1in"/>
<Align HAlign="Center" VAlign="Middle"/>
<Value> <Ellipse>
<Edge Thickness="1pt">
<Color Value="0,128,0"/>
</Edge>
<Fill> <Color Value="128,128,128"/>
</Fill>
</Ellipse>
</Value> </Draw> </Subform>
Positioned objects are located within a coordinate system mapped into the nominal content region of the enclosing container. The location is specified via a pair of measurements representing X and Y coordinates.
A positioned object is located by an anchor point which is typically the top-left corner of the container's nominal extent. However, mechanisms are provided for altering this behavior as described below.
All positioned containers have three parameters that specify how they are positioned within their enclosing containers:
The following diagram shows where the anchor point types map onto the container's nominal extent.
|
|
Diagram POSITION-1 -- Anchor point locations
|
The enclosing container positions a child container in the following manner:
For more information on the mechanics of the transformations that occur during positioning, see the section "Transformations".
While containers themselves are positioned, content is flowed inside an enclosing container. As illustrated by the following example, while a Draw object may have an (x,y) coordinate that determines its position, the content inside the draw object (in this case some text) cannot assert a position and may only be flowed inside its enclosing draw object.
<Draw X="0" Y="0"> <Value> <Text>Hello world</Text> </Value> </Draw>
Flowed objects delegate a great degree of control over their locating to their enclosing container. The container typically employs some sort of wrapping technique to place a long stream of flowed content into its nominal content region. Text is typically flowed over one or more lines, breaking at word boundaries. The height of each line is determined by the line height.
The following diagram illustrates flow of mixed text and graphical content placed along a horizontal flow axis:
|
|
Diagram FLOW-1 -- Flowed content placement
|
Note that there are two issues of particular importance:
The baseline is positioned up from the bottom of the line height by the maximum descent of all symbols and objects in that line. So, if the line contains only a non-text object, the baseline will be at the bottom of the line height.
To flow text and other flowed objects, the application may have to choose break points for wrapping. The result is that the flowed content is rendered as a series of one or more lines. The height of each line is known as the line height. Line height is typically determined from the current font, or if multiple fonts are used in a line, from the font that asserts the maximum height in the line.
Presenting the form to the user, or printing it to paper, requires that the many objects inside the template be assembled by the processing software. During this assembly, many transformations must take place. Container objects must position or flow their enclosed objects within the enclosing containers' coordinate spaces.
This section describes the transformations required. Note that we use the term parent to refer to the enclosing container, and child to refer to the enclosed object.
It is not the responsibility of this document to mandate the actual implementation of transformations beyond the specification of the transformations themselves. However, by describing one possible implementation, transformation calculations become more obvious. This particular implementation is provided to be illustrative of transformations.
In this implementation there is a clear separation between what the child object knows and what the enclosing parent container knows. Regardless of margins and the internal coordinate origin, a child object makes coordinates available to the parent relative to its (the child's) top-left corner. The parent can then take these common coordinates and transform them into its own coordinate space.
Suppose, for example, a child object places its internal origin at the top-left corner of its nominal content region (the typical case). If we have a point (Cx,Cy) in child coordinates, we can generate common coordinates (CCx,CCY) for the parent with the following simple equations:
where Mx and My are the left and top margin insets, respectively.
In order to convert these common coordinates into its own space, the parent must first determine the origin (Ox,Oy) of the child's top-left corner in its own coordinate space. These would be computed from the child's anchor point (Ax,Ay), using the child's nominal extent's width and height (W,H) as follows:
Now, it's a very simple transformation to generate parent coordinates (Px,Py) from common coordinates:
Or,
A slight optimization could be to avoid recalculating the invariants (Mx+Ox, My+Oy) through a little cooperation between the parent and the child.
The designer can designate a container object as being "growable"--its size may change at run-time. Growable objects are very useful in forms processing environments. Growth may occur along either the X and Y axes as follows:
When a user utilizing GUI-based form design software places an container object on the form, the software application typically works form the outside-in. It starts with the rectangle drawn by the designer and applies the margins to determine the available content region. The growing ability of a container object tends to be more important at run-time. When a container object is growable, the run-time application typically works from the inside-out. It computes a content region from the container's contents and then applies the margins to determine a (dynamic) nominal extent.
There are a lot of implications that result from the ability of container objects to grow, as described in the following subsections. At a minimum, the requirement that container objects can grow means that all container objects must have the potential of attributes for minimum size (attributes MinW/MinH) and maximum size (attributes MaxW/MaxH). However, since majority of container objects on a form do not exhibit growth, we permit a simpler way to describe the size of a container object via width and height attributes (W/H respectively).
The interpretation of an empty string for any of the MinW, MinH, MaxW, MaxH measurements is not to constrain the corresponding aspect of growth. For example, specifying MinW as an empty string allows the width to shrink to zero. Specifying MaxW as an empty string allows for unlimited growth of the width. Growth larger than the presentation medium results in application-defined behavior. The absolute omission of any of these attributes causes the attribute to be interpreted as an empty string.
Specifying the width and height via the W/H attributes, is exactly the same as specifying a MinW attribute that equals the MaxW attribute, and a MinH attribute that equals the MaxH attribute, which both equal the values specified in W and H respectively. In this case the processing application should always behave as if the Min/Max attributes exhibit values derived from the W/H attributes. Specifying W or H attributes in addition to a MinW, MaxW, MinH, or MaxH attributes is allowed, but the W and H attributes have precedence over the MinW/MinH and MaxW/MaxH attributes; that is, the MinW/MinH and MaxW/MaxH will be ignored in this case.
Typically, a growable object grows or shrinks when the geographical size of its content changes. The object responds to the size change by adjusting the size of its nominal content region to appropriately enclose the content. As a result, this triggers a change in the container's nominal extent, to keep the box model consistent. The change in nominal extent may cause the container's parent to adjust itself, possibly changing its own size as well. Note that some of an container's graphical content may be outside the nominal extent both before and after the size changes. It's up to the object to manage this in a way that is intuitive for users of the object.
It may be helpful to think of transformations as occurring after growth. An object establishes its new nominal content region in the coordinates it is comfortable with. Next, applies the box model embellishment. Only then does it do transformations.
Growth always occurs away from the anchor point in the directions defined by the anchor type. For example, a TopRight anchored object will grow only to the bottom and the left, while a MiddleCenter anchored object will grow evenly in all four directions.
When a positioned object grows, we say that the growth is "destructive"--the growing object may become large enough to overlap and obscure other sibling objects that occur beneath it according to Z-order. Note that the overlap is apparent only in the presentation of the objects, the obscured objects continue to exist in the form in their entirety.
A positioned object may grow sufficiently such that part of it extends outside its enclosing parent's nominal extent. What happens in this case is dependent on how the parent is defined. If the parent is of a fixed size (i.e., not capable of growing), part of the child object may simply be clipped to the parent's nominal extent. If the parent is capable of growth, its nominal content region is adjusted to accommodate the offending child object, causing the parent's nominal extent to grow appropriately. The visible effects of this parental growth depend on how the grandparent is defined, as well as the great-grandparent, and so on.
When a growable parent object contains positioned child objects, we have to deal with the case where a child appears partially or wholly outside the parent's current nominal extent. Typically, if the parent is capable of growth, the parent's nominal extent would adjust to enclose the nominal extent of the child. Such behavior seems intuitive when one considers the parent in isolation. However, two interesting implications fall out of this behavior. First, suppose the parent's internal origin is at its top-left corner. The addition of a child above or to the left of the current nominal extent will typically cause the parent to record negative coordinates for the new child. Negative coordinates are not strictly a problem, as long as the parent continues to assert its new nominal extent to the grandparent. But we must note that the parent's coordinate mathematics may have just become a little more complicated.
The second implication occurs when the parent object itself is positioned in the grandparent. Additions of child objects to the parent will cause growth away from the anchor point within a growable grandparent. This may or may not produce intuitive results. For example, suppose the parent is anchored by its top-left corner in the grandparent. Adding a child below the bottom of the parent causes intuitive growth: the parent just gets larger in Y to accommodate the child. On the other hand, adding a child above the parent's current nominal extent causes the parent's nominal extent to grow upward (in the immediate context of the parent of the child). However, since the grandparent positions the parent's nominal extent (and not its internal origin) at the anchor point, the effect is that the contents of the parent object appear to shift downward with respect to the grandparent.
The content within a container object may describe a number of formatting characteristics. This specification provides the following formatting characteristics:
Alignment is applicable to flowed content only, and determines how the content shall be positioned within the enclosing container object.
Alignment is divided into two axes, horizontal and vertical, with the following values which are combined to refer to a specific alignment:
When text has an alignment of Justify, space is inserted between words so that the first and last word of the text lines are aligned against the margins. Normally, the last line of a justified paragraph is treated only as left aligned, with a ragged right edge. An alignment of Justify All causes justification to occur on the last line as well.
The following diagram demonstrates how nine common alignments affect the positioning of text.
 |
|
Diagram ALIGNMENT-1 -- Nine common text alignments
|
Though alignment is most often thought of in terms of text, it applies to other forms of content as well.
Any closed graphic can be filled. Closed graphics include the box model Border, as well as some content objects, such as Rectangle and Arc. The Fill element indicates how the region enclosed by the graphic is to be filled. Types of fill include:
The Fill element has a child color element. One can often think of this as specifying the background color for the fill. The Fill element also has a child element specifying the type of fill (e.g., Solid, Pattern, Linear, Radial). Stipple, This child, in turn, has its own child Color element. This second color can often be thought of as the foreground color. For example, the following would create a fill of horizontal black lines on a gray background.
<Fill> <Color Value="128,128,128"/> <Pattern Type="Horizontal"> <Color Value="0,0,0"/> </Pattern> </Fill>
Note that the absolute omission of a <Fill> element signifies no fill (transparent fill). If the <Fill> element is present, but all attributes and subelements are omitted, it signifies solid white fill.
Each container object may include a caption. Some common purposes for the caption include:
One can see that the rendering of the caption and its behavior are quite closely tied to the particular user interface for the container. Different user interface elements may place the caption in different ways. More detail on caption handling can be found in the description of each user interface element.
The above caption examples all involve textual captions. In actual fact, a caption could be of any content type. The Caption element actually represents a subset of the functionality of the Draw element, with child elements for alignment, margins, font and value.
Any sort of a line, whether it be a line element or a border edge, follows a logical path. This path has zero width. During the process of rendering of the line, however, the application applies a thickness to create a visible line. Handedness provides the forms designer with a means to specify how that thickness is applied to the line.
This specification describes two elements that represent strokes: Edges, and Corners.
Many XFA elements that represent graphical objects (such as lines,
rectangles, and borders)
have outlines that are rendered according to one or more <Edge>
and/or <Corner> subelements.
These elements possess an attribute which determines the thickness of the stroke, and as the thickness increases the stroke appears to become wider and spread in one or more directions. To understand this, recognize that a stroke is a vector possessing a point of origin, and a measurement representing the length; the imaginary line that extends from the origin along the length is the stroke's path. Therefore, there are three different ways for the thickness of a stroke element to be defined:
The following diagram illustrates the three possibilities, as three thick black strokes along a common path shown in green.
 |
|
Diagram HAND-1 -- Edge thickness rendering
and handedness
|
The elements that produce the above diagram are:
<Draw X="1in" Y="1in" W="0.6in" H="0.8in"> <Value> <Line Hand="Left" Slope="/"> <Edge Thickness="0.2in"/> </Line> </Value> </Draw>
<Draw X="2in" Y="1in" W="0.6in" H="0.8in"> <Value> <Line Hand="Even" Slope="/"> <Edge Thickness="0.2in"/> </Line> </Value> </Draw>
<Draw X="3in" Y="1in" W="0.6in" H="0.8in"> <Value> <Line Hand="Right" Slope="/"> <Edge Thickness="0.2in"/> </Line> </Value> </Draw>
Borders and rectangles are drawn from the top-left corner, in a clockwise direction. Therefore, a left-handed border will appear to draw immediately outside the border's path; a right-handed border will appear to draw immediately inside the border's path; and an evenhanded border will appear to straddle the border's path. Each one of these options has some value to the form designer, who typically designs forms with border margin insets of zero:
It is this last point that is of greatest use to a forms designer. If the stroked edges of a border are evenhanded, the edges will appear to spread outside the container's nominal extent by half the edge thickness. Placing two objects with this type of border adjacent to each other will result in the common border edge between the two objects, appearing to have the same width as all the other edges -- this is very common to traditional form composition.
If the border had been right-handed causing the stroked edges to be rendered completely inside the nominal extent, or left-handed causing the stroked edges to be rendered completely outside the nominal extent, there would appear to be a doubly thick border between the two objects.
This effect of handedness on adjacent bordered objects is illustrated by the following diagram:
|
|
Diagram HAND-2 -- Border handedness
|
In the above diagram, note how evenhanded borders avoid the doubly thick line between the two bordered objects.
The elements that produce the above diagram are:
<Field X="1in" Y="1in" W="1.5in" H="1in"> <Border Hand="Right"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field> <Field X="2.5in" Y="1in" W="1.5in" H="1in"> <Border Hand="Right"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field>
<Field X="1in" Y="2.5in" W="1.5in" H="1in"> <Border Hand="Even"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field> <Field X="2.5in" Y="2.5in" W="1.5in" H="1in"> <Border Hand="Even"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field>
<Field X="1in" Y="4in" W="1.5in" H="1in"> <Border Hand="Left"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field> <Field X="2.5in" Y="4in" W="1.5in" H="1in"> <Border Hand="Left"> <Edge Thickness="0.125in"> <Color Value="128,128,255"/> </Edge> </Border> <Value><Text/></Value> </Field>
While the form coordinate space is two-dimensional, it should be recognized that container objects appear to exist at different depths. Objects at shallower depths (closer to the user) may visibly obscure parts of objects at deeper depths. This notion of a depth-based order is the Z-order of the form. One can think of objects that come early in the Z-order as being placed on the presentation media earlier in the construction of the form. Objects that come later are placed over top of the earlier objects.
Each Subform and Area encloses other container objects. The Subform or Area imposes an implicit Z-order for those containers, which is simply the order in which the children occur; the first object exists at a deeper Z-order depth than the last object. This is convenient for many drawing APIs, where objects drawn later appear on top of objects drawn earlier.
Within an container's box model, there is also a Z-ordering. Content will always appear on top of the border when the two overlap.
When a form designer takes advantage of growable objects, clipping is generally not an issue. However, if an object is of a fixed size, but contains content that may grow, it is possible for some content to be clipped.
In general, clipping occurs at a form container object's nominal content region. With certain commonly used exceptions, a container's graphical rendering will not appear outside its nominal content region. This is true for containers of containers as well. For example, fields and draw elements within a subform will generally not draw outside that subform's nominal content region.
The most notable exception to the clipping rule is the handling of an container's borders. Borders will draw outside the container's nominal content region. In addition, edges on Rectangle, Line and Arc graphical content may overflow the container's nominal content region, depending on the placement, thickness and handedness of the edge.
Areas and Subforms clip their children to their nominal content regions. This is true for borders and graphical content, subject to the placement, thickness and handedness considerations mentioned in the previous paragraph. In other words, an object is free to place its border entirely outside its nominal content region and that border will not be clipped. However, if their border extends outside the parent container's nominal content region, that border may be clipped.
Note that it is a graphical object's path that is clipped, not necessarily the object's actual rendering. Certain renderings, such as evenhanded lines, may draw outside the path and are clipped only inasmuch as the path is clipped.
All of this is best explained by way of example. Consider the following subform with two fields. All margins are zero, so that nominal content regions are aligned with nominal extents.
 |
|
Diagram CLIPPING-1 -- Clipping and borders
|
The thin dotted lines indicate nominal extents and the thick colored lines indicate evenhanded borders. The elements for the above form might be as follows:
<Subform X="1in" Y="1in" W="3in" H="2in"> <Border Hand="Even"> <Edge Thickness="4.5pt"> <Color Value="0,0,255"/> </Edge> </Border>
<Field X="0.5in" Y="0in" W="1in" H="0.5in"> <Border Hand="Even"> <Edge Thickness="9pt"> <Color Value="0,128,0"/> </Edge> </Border> <Value><Text/></Value> </Field>
<Field X="2.5in" Y="1in" W="1in" H="0.5in"> <Border Hand="Even"> <Edge Thickness="9pt"> <Color Value="0,128,0"/> </Edge> </Border> <Value><Text/></Value> </Field> </Subform>
The first field's nominal content region does not extend beyond the nominal content region of its parent. Therefore, it is not clipped at all and the field's border is free to draw where it lies, even if this involves drawing outside the nominal content region, or even the border, of the parent subform. The second field's nominal content region does extend beyond the nominal content region of the its parent subform. Therefore, this field's nominal content region is clipped to the nominal content region of the subform, resulting in a clipped border for the field.
Note that while it is common for a container object's nominal content region to be aligned with the nominal content region of its parent container, it is unusual for its nominal content region to extend beyond that of its parent. In other words, the clipped field in the above example represents a rare occurrence.
A form typically contains a great number of duplicated or similar objects; the same fonts, colors, borders, etc. are used repeatedly throughout the form. Often, there are objects such as lines, rectangles, and even whole field and draw objects repeated.
This presents an opportunity to significantly reduce the file-size of a form template, by factoring out the common aspects of the form into prototypical objects. As an additional benefit, the form designer may easily apply sweeping change to the form template by applying changes to a prototypical object and any objects that are based upon that object will receive the changes.
Almost any XFA template element can be enclosed within a <Proto>
element. An element enclosed in such a way is called a Prototype. A prototype
may have child elements. Though these are part of the parent prototype, they
are not prototypes themselves. Only the direct children of <Proto>
elements are considered prototypes. For example, the following defines a prototype
font with a particular color, but the color is not itself a prototype.
<Proto> <Font ID="HELV-RED" Typeface="Helvetica" Size="10pt" Weight="Regular" Posture="Upright"> <Color Value="255,0,0"/> </Font> </Proto>
Prototypes don't participate directly in the form. Instead, their participation is indirect only, when referenced by another element. For example, a prototype field, even though fully specified, will never be directly visible or accessible to a form filling user.
The <Proto> element itself
can appear only as a child of a container
element. The container may hold more than one <Proto>
element for multiple prototypes, or the prototypes may be grouped in a single
<Proto> element. For example,
the following are equivalent.
<Subform> <Proto> <Color ID="RED" Value="255,0,0"/> </Proto> <Proto> <Color ID="GREEN" Value="0,255,0"/> </Proto> ...
<Subform>
and
<Subform> <Proto> <Color ID="RED" Value="255,0,0"/> <Color ID="GREEN" Value="0,255,0"/> </Proto> ...
<Subform>
Almost any template element can be a prototype. Notable exceptions include
<XFA>, <Template>
and <Proto>.
An element can refer to a prototype through its Use attribute. This takes a fragment identifier as a reference to the prototype element. For a successful reference to occur, the reference must:
<Proto>
elementFor example:
<Proto> <Font ID="HELV-RED" Typeface="Helvetica" Size="10pt" Weight="Regular" Posture="Upright"> <Color Value="255,0,0"/> </Font> </Proto>
<Field ...> <Font Use="#HELV-RED"/> ...
</Field>
This defines a field whose font is red 10pt Helvetica regular. Note that several fields would likely reference this font prototype, thereby reducing file size and allowing for global format changes.
Prototypes may reference other prototypes. In addition, descendant elements of a prototype may reference prototypes. For example,
<Proto> <Color ID="RED" Value="255,0,0"/>
<Font ID="HELV" Typeface="Helvetica" Size="10pt" Weight="Regular" Posture="Upright"> </Font>
<Font ID="HELV-RED" Use="HELV"> <Color Use="#RED"/> </Font> </Proto>
<Field ...> <Font Use="#HELV-RED"/> ...
</Field>
This achieves the same effect as the previous example, only the prototype and
its <Color> element refer to
other prototypes.
A prototype can be resolved in one of two ways, controlled by the UseType attribute on the referencing element:
The two values of this attribute effectively give the form designer the classic choice between performance (ByVal) and space (ByRef).
An element that references a prototype is said to inherit all of the attributes, data content and child elements of that prototype. When an element references a prototype, it has the option of overriding what gets inherited. The general rule for inheritance is that a referencing object inherits the following:
Where the referencing element does not explicitly provide values for attributes, child elements, and data content, and no such values are inherited from the referenced prototype (referred to as absolute omission by this specification), application defaults shall apply.
Any attribute present in an element overrides that attribute from the prototype. For example, consider the following:
<Proto> <Font ID="HELV-RED" Typeface="Helvetica" Size="10pt" Weight="Regular" Posture="Upright"> <Color Value="255,0,0"/> </Font> </Proto>
<Draw ...> <Font Use="#HELV-RED"/> <Value> <Text>Helvetica 10pt</Text> </Value> </Draw>
<Draw ...> <Font Use="#HELV-RED" Size="14pt"/> <Value> <Text>Helvetica 14pt</Text> </Value> </Draw>
This defines two <Draw> elements
whose fonts both reference the 10pt Helvetica prototype. However, the second
one overrides the font size with a size of 14pt, and so, it will draw with a
font of 14pt Helvetica. In the first <Draw>
element's font, the font size was omitted, so it is inherited from the prototype.
As implied in the previous paragraph, an attribute is considered to be omitted only if it was not explicitly specified with a value on an element. An attribute that is explicitly specified on an element with the value of an empty string is not considered to be omitted; as should be obvious, the attribute is specified as having the value of an empty string, which signifies the application default.
One impact of this inheritance mechanism is that XFA elements have attributes which must be defined in a DTD as CDATA, as opposed to enumerations.
The presence of data content in a referencing element overrides data content from the prototype. For example:
<Proto> <Text ID="TEXT" NullIfEmpty="0"/>Default text</Text> </Proto>
<Field ...> <Value> <Text Use="#TEXT">Overriding text</Text> </Value> </Field>
The text value of the field will be "Overriding text". The field's
<Text> element does inherit
the NullIfEmpty attribute. Note that it is not possible to override
prototype data content with empty data content.
When both the referencing element and the prototype contain child elements, those child elements are matched first by type and then by ordinal number within type. If the prototype has a child element of a particular type and the referencing element does not, the referencing element inherits the child from the prototype. When the child is present in both, the prototype's child acts as a prototype for the referencing element's child. In other words, the referencing element's child will inherit attributes and grandchild elements from the prototype, as long as it doesn't override them. Consider the following example:
<Proto> <Field ID="DEFAULT-FIELD"> <Font Typeface="Helvetica" Size="10pt" Weight="Bold"> <Color Value="255,0,0"/> </Font> <Value><Text/></Value> </Field> </Proto>
<Field Use="#DEFAULT-FIELD" X="1in" Y="1in" W="1in" H="14pt"> <Border> <Edge Thickness="1pt"/> </Border> <Font Typeface="Times" Size="12pt"/> </Field>
Here we have a field that inherits from a prototype <Field>
element. It's interesting to examine the treatment of four child elements:
<UI>: Omitted from both
the referencing field and the prototype. Application default applies.<Border>: Present in the
referencing field, but omitted from the prototype. Referencing field's <Border>
element applies, along with its child, <Edge>.
Application defaults are invoked for any omitted border attributes.<Value>: Omitted from the
referencing field, but present in the prototype. Referencing field inherits
<Value> (and its child, <Text>)
from the prototype.<Font>: Present in both
the referencing field and the prototype. Referencing field's child <Font>
element inherits from prototype's <Font>
child element.The last case is of special interest. Because <Font>
is present in the both the prototype and the referencing field, we can recursively
view the prototype's <Font>
element as being a prototype for the referencing field's <Font>
element. In other words, the referencing field will have a font of Times 12pt
bold, colored red.
When an element can have repeating child elements, overrides are matched by ordinal number. For example, consider the following:
<Proto> <Border ID="DEFAULT-BORDER"> <Edge Thickness="2pt"/> <Edge Thickness="1pt"/> </Border> </Proto>
<Field ...> <Border Use="#DEFAULT-BORDER"> <Edge Thickness="3pt"/> </Border> ...
</Field>
The prototype border specifies two edges, which are taken as the top/bottom and left/right edges. Using the prototype without any overrides would therefore result in 2pt edges along the top and bottom borders, and 1pt edges along the left and right. The prototype reference, however, overrides the first edge element. So, the result would be 3pt edges along the top and bottom of the border and 1pt edges at the left and right.
The purpose of this section is to describe the XFA Scripting Object Model (XFA-SOM), the types of objects available when scripting electronic forms (e-forms), and the rules for locating those objects.
We expect that a reader familiar with DOM and the HTML scripting object models exposed by web browsers via ECMAScript and VBScript may already be familiar with many of the concepts described in this section. However, in the interest of completeness, this specification reviews many of the basic concepts prior to introducing XFA specific features.
The actual implementation of a forms-processing application may very well use Active-X components, Java Beans or some other technology that, in effect, has its own model. Moreover, an open forms processing architecture must allow for the inclusion of third-party controls or Beans on a form. All of these participate in a physical model. The physical model is likely dependent on both the platform and application.
For maximum portability, scripting would be limited to the logical model. However, there may be occasions where an advanced user would prefer scripting access to the physical model. For example, such a user might use certain components or Beans both within a forms-processing application and with other application development tools available on the platform. Consequently, both the logical and physical models make up the XFA-SOM.
The XFA-SOM is also concerned with the Scripting Environment; the combination of a scripting engine and the language syntax implemented by that engine.
XFA is architecture-neutral. XFA does not place requirements or restrictions on the architecture of a software application that implements XFA. The XFA-SOM allows for a clear separation between scripting environment and model. While the two operate in concert, a scripting environment has no knowledge about a particular model; nor does a model require any knowledge about a particular scripting environment. It is up to the model to to expose its internal objects and properties into the scripting environment. In addition, the model must support the concept of named objects, and certain types of access by object name. Object naming is a critical XFA-SOM concept, and will be discussed in more detail in subsequent subsections.
Note that XFA-Template concepts and terminology are used in many of the discussions below. This is not to say that a model is restricted to implementing the XFA-Template model. It must, however, implement appropriate features to support the XFA-SOM.
XFA defines a form calculation-oriented scripting language, FormCalc [FORMCALC], to satisfy those who do not want to step over the programming threshold. Advanced users might prefer to forgo FormCalc and use one of the scripting environments available with their platform. However, FormCalc does have a grammar and feature set tailored specifically to the common operations that occur within forms; the result is that users of all skill levels can express powerful operations with minimal instruction and effort.
In general, FormCalc and other scripting environments all expose the same XFA-SOM. However, some differences do exist, for the following reasons:
Throughout this document, we tend to use the term Object to refer to a node in the model's hierarchy. For a particular object, the model stores its attributes and children. There is also an implicit link to its parent. The model exposes an object's attributes and children as Properties. A property is a name/value pair, where the name identifies that property in the context of an object. The value of a property might be a basic type (e.g., string, number), or it may be another object. If it is another object, that object may, in turn, also expose properties.
Generally, a model exposes object attributes as properties simply by mapping directly between attribute names and property names. Similarly, it exposes child objects by mapping directly between child element type names (in XML, tag names) and property names. A model can also manufacture properties; properties that it exposes, but doesn't explicitly store.
The script writer can make references to properties through scripting language syntax, interrogating or changing values as required.
XFA-SOM is a model specification, not a scripting language, so one may find it odd that XFA-SOM has a syntax. However, there are syntactic shortcuts that are useful for object referencing, shortcuts that could save a lot of procedural scripting. These shortcuts become the syntax of XFA-SOM.
XFA-SOM syntax is primarily about naming objects. The syntax allows a form designer to refer to an object simply by naming it. XFA-SOM syntax constructs also allow the following:
The syntax has been designed to keep both the syntax itself and the semantics of the syntax intuitive and convenient for form designers. Because XFA-SOM obviates the need to navigate model hierarchy in many cases, it is possible to design a form that operates with different underlying object models.
FormCalc adopts XFA-SOM syntax as a native part of its syntax. A designer can code XFA-SOM syntax in FormCalc without resorting to escapes such as quoting.
Other scripting languages have their own syntactic conventions. Indeed, XFA-SOM syntax may be incompatible with the syntax of a particular scripting language. We address this by providing in XFA-SOM a small number of accessors. These accessors take string arguments that can contain XFA-SOM syntax. The functionality of XFA-SOM accessors is also available in FormCalc, as properties.