Sei sulla pagina 1di 33

Adobe XML Architecture

Scripting Object Model Expression Specification


Version 2.0

Adobe Systems Incorporated


October 2003
2003 Adobe Systems Incorporated. All rights reserved.
This publication and the information herein are furnished AS IS, are subject to change without
notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe
Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes
no warranty of any kind (express, implied, or statutory) with respect to this publication, and
expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and
noninfringement of third-party rights

This page is left intentionally blank.

NOTICE: All information contained herein is the property of Adobe Systems Incorporated.
Any references to company names in the specifications are for demonstration purposes only and are not intended to refer to any
actual organization.
Adobe is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries.
All other trademarks are the property of their respective owners.
This limited right of use does not include the right to copy other copyrighted material from Adobe, or the software in any of Adobes
products that use the Portable Document Format, in whole or in part, nor does it include the right to use any Adobe patents, except
as may be permitted by an official Adobe Patent Clarification Notice (see the Bibliography).
Intellectual Property
Adobe will enforce its intellectual property rights. Adobes intention is to maintain the integrity of the Adobe XML Architecture
standard. This enables the public to distinguish between the Adobe XML Architecture and other interchange formats for electronic
documents, transactions and information. However, Adobe desires to promote the use of the Adobe XML Architecture for
information interchange among diverse products and applications. Accordingly, Adobe gives anyone permission to use Adobes
intellectual property, subject to the conditions stated below, to:

Prepare files whose content conforms to the Adobe XML Architecture

Write drivers and applications that produce output represented in the Adobe XML Architecture

Write software that accepts input in the form of the Adobe XML Architecture specifications and displays, prints, or
otherwise interprets the contents

Copy Adobes intellectual property, as well as the example code to the extent necessary to use the Adobe XML
Architecture for the purposes above

The condition of such intellectual property usage is:

Anyone who uses the Adobe intellectual property, as stated above, must include the appropriate intellectual property and
patent notices.

This limited right to use the example code in this document does not include the right to use other intellectual property from
Adobe, or the software in any of Adobes products that use the Adobe XML Architecture, in whole or in part, nor does it include the
right to use any Adobe patents, except as may be permitted by an official Adobe Patent Clarification Notice (see the Bibliography).
Adobe, the Adobe logo, and Acrobat are either trademarks or registered trademarks of Adobe Systems Incorporated in the United
States and/or other countries. Nothing in this document is intended to grant you any right to use these trademarks for any purpose.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software
and Documentation are Commercial Items, as that term is defined at 48 C.F.R. 2.101, consisting of Commercial Computer
Software and Commercial Computer Software Documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202,
as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial
Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only
as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San
Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws
including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans
Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the
regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the
preceding sentence shall be incorporated by reference.

This page is left intentionally blank.

ii

Table of Contents
1
2

4
5

7
8

Introduction ...................................................................................................................................................................... 1
1.1
Using XFA-SOM...................................................................................................................................................... 1
1.1.1
Purchase Order Example .................................................................................................................................... 1
Object References .............................................................................................................................................................. 5
2.1
Containers................................................................................................................................................................ 5
2.2
The Current Object ................................................................................................................................................. 5
2.3
Container Names..................................................................................................................................................... 6
2.4
Compound Object Names ...................................................................................................................................... 6
Accessing Properties.......................................................................................................................................................... 7
3.1
The value Property .................................................................................................................................................. 7
3.1.1
Other value properties ........................................................................................................................................ 7
3.2
Accessing Properties that are Elements .................................................................................................................. 8
3.3
Accessing Properties that are Attributes................................................................................................................. 8
3.4
Name clashes............................................................................................................................................................ 9
Accessing Methods .......................................................................................................................................................... 11
Scoping Rules................................................................................................................................................................... 12
5.1
Containers are the Most Basic Units for Scoping ................................................................................................ 12
5.2
Sibling Containers are Accessible ......................................................................................................................... 12
5.3
Subforms and Exclusion Groups Form a Scoping Context ................................................................................ 13
5.4
Anonymous Subforms and Exclusions Groups are Transparent........................................................................ 13
5.5
Areas are Transparent ........................................................................................................................................... 14
5.6
Subform Ancestry.................................................................................................................................................. 15
5.7
Duplicate Names ................................................................................................................................................... 16
Multiply Occurring Objects............................................................................................................................................ 18
6.1
Purchase Order with Single Detail........................................................................................................................ 18
6.2
References Relative to Current Occurrence ......................................................................................................... 20
6.3
Effect of Hierarchy on Multiply Occurring Object References........................................................................... 21
Identifiers and Tokens for Accessing Nodes.................................................................................................................. 23
Bibliography..................................................................................................................................................................... 28

iii

1 Introduction
XFA-Scripting Object Model (XFA-SOM) is a model for referencing values, properties and methods within a particular
Document Object Model (DOM). A DOM structures all objects and properties in memory as a tree hierarchy. XFASOM expressions provide easy access to these objects and properties through a straightforward object reference syntax.
This syntax is described in detail later in this specification.
XFA-SOM expressions, in combination with a scripting environment, can be used to quickly and easily perform a
variety of functions without requiring extensive coding. Through the use of various notations, accessors, and operating
rules, XFA-SOM defines ways to reference specific objects, groups of objects, or even objects whose name is unknown
but whose position within the tree is known.
XFA-SOM interacts with any XFA-DOM, and may appear in a form template, XML data, configuration information, or
on the command line. It is the responsibility of a scripting environment to expose the appropriate objects and
properties to XFA-SOM. As such, referencing unexposed objects or properties is not possible.
The syntactic grammar for XFA-SOM expressions is described in [XFA-FormCalc], Accessors.

1.1 Using XFA-SOM


XFA-SOM expressions may be used in scripting expressions (including [XFA-FormCalc]) as well as in the ref property
([XFA-Template] and [XFA-Data Binding]), which is used for accessing data in the XFA Data DOM [XFA-Data
Handling].
For example, this FormCalc expression contains an XFA-SOM expression (highlighted in red):
Sum(Detail[*].Total_Price)

The dataRef node can bind to any node in the Data DOM using XFA-SOM:
<field name="Final_Price"><bind match="dataRef" ref="$data.PO.Price"></field>

1.1.1 Purchase Order Example


This Purchase Order Example is an example of an XFA-Template with embedded XFA-SOM expressions. It will be
referenced in later sections of this specification. The template consists of a root subform, which contains fields, static
text, and subforms. Each subform may contain fields, static text, and subforms. In the figure below, subform names are
displayed in blue and field names are displayed in green.

Figure 2: Blank Template as Displayed or Printed


In the tabular part of the form, there are five subforms named Detail; each Detail subform contains a field called
Item, Description, and so on. Duplicate field names are common in XFA and very natural to the form
designer. Note also that there are fields called Total_Price in the Detail subform and one field called
Total_Price in the PO subform. The Vendor subform contains a field called name.
2

XFA-SOM is structurally represented as a tree hierarchy with a single root object (or node) with a potentially unlimited
number of child objects (or nodes). The following diagram shows a tree view of the Purchase Order template (subforms
are displayed in blue and fields in green):

Figure 3: Template displayed as a tree


XFA-SOM provides the syntax for accessing these nodes and their properties. XFA-SOM expressions embedded in the
XFA-Template are highlighted in red below. The validity of an XFA-SOM expression is subject to object references for
referring to nodes in the tree and scoping rules that provide the context for name resolution.
The XFA-Template version of the Purchase Order is shown below:
<template name="Static List Example">
<subform name="PO">
<field name="PO_Date" ...>...</field>
<field name="Req_No" ...>...</field>
<field name="Vendor_Code" ...>...</field>
<subform name="Vendor">
<field> name="name" ...>...</field>
<field name="address1" ...>...</field>
<field name="address2" ...>...</field>
<field name="address3" ...>...</field>
</subform>
<subform name="Detail">
<field name="Item"...>...</field>
<field name="Description"...>...</field>
<field name="Units"...>...</field>
<field name="Unit_Price"...>...</field>
<field name="Total_Price"...>...</field>
</subform>
<subform name="Detail>
<field name="Item"...>...</field>
<field name="Description"...>...</field>
<field name="Units"...>...</field>
<field name="Unit_Price"...>...</field>
<field name="Total_Price"...>...</field>
</subform>
... 3 more subforms named Detail ...
<field name="Sub_Total"...>
<calculate>

<script>Sum(Detail[*].Total_Price)</script>
</calculate>
...
</field>
<field name="Tax"...>
<calculate>
<script>Sub_Total * 0.075</script>
</calculate>
...
</field>
<field name="Total_Price"...>
<calculate>
<script>Sub_Total + Tax</script>
</calculate>
...
</field>
<field name="Del_Instr"...>...</field>
</subform>
</template>

2 Object References
XFA-SOM expressions provide the means to reference containers within the DOM.

2.1 Containers
Within XFA there is a concept of a container. A container is an object that holds data or values. Simple containers
include field (interactive element on the form) and draw (static) elements. Hierarchical containers include subforms,
areas, and exclusion groups. More information about containers may be found in [XFA-Template], Template
Overview, Form Structure, Containers.
The elements that correspond to XFA containers are:

field
draw
area
subform
exclGroup

2.2 The Current Object


In XFA-SOM, the current object is the XFA container that is the most immediate ancestor of the script fragment.
Typically, such containers are fields.
In the following example of an XFA-SOM expression embedded in a script element, the current object is the
Sub_Total field, the most immediate ancestor that is an XFA container. The script sets the value of the current object,
which is the Sub_Total field. The XFA-SOM expression is evaluated using scoping rules relative to the current object.
<field name="Sub_Total"...>
...
<calculate>
<script>Sum(Detail[*].Total_Price)</script>
</calculate>
...
</field>

Each XFA container can have a number of scripts attached to it for different events. Some of these (e.g., calculation and
validation rules) are defined as part of [XFA-Template]. Others are not (e.g., specialized event on a third-party userinterface control). These scripts are often nested in the sub-hierarchy of objects under the field. Less frequently, the
scripts are included in an attribute on the container. When an event fires off the XFA script or third-party control, the
current object is XFA container (usually a field) that contains the control.
The XFA-SOM identifier for the current object is the dollar sign, $. This serves a purpose similar to this in
ECMAScript or Me in VBScript.

2.3 Container Names


In XFA-SOM, containers can be referenced by using the value of the name attribute. The container name is one of the
building blocks of a compound object name. The following example shows containers named PO , PO_Date, and
Req_No.
<subform name="PO">
<field name="PO_Date" ...>...</field>
<field name="Req_No" ...>...</field>
...
</subform>

All containers can have a name attribute. Names provide a convenient means for form designers to refer to objects, for
example, PO_Date and Req_No are simple XFA-SOM expressions. There is no requirement that name attributes have
unique values within the model. In the Purchase Order Example, the subform named Detail appears multiple times.
Subsequent sections describe how ambiguities with multiply occurring names are resolved.

2.4 Compound Object Names


Compound object names are a way of navigating down through the hierarchy of containers; each level of the hierarchy
is separated by a dot ('.'). All XFA-SOM expressions begin with a reference to a named container or one of the special
identifiers (such as $ and $template) that can stand in for a container. The compound object name is resolved
according to scoping rules.
Some compound object names from the Purchase Order Example are:
PO.PO_Date
Vendor.address1

The following compound object name uses array-referencing syntax to access the second Detail (the array index
begins at 0):
PO.Detail[1].Total_Price

There are other predefined identifiers and tokens that can be used in compound object names. For more information,
see Identifiers and Tokens for Accessing Nodes.

3 Accessing Properties
An XFA-SOM expression allows access to the properties of a container. Properties can be subelements and attributes of
a container or the value property. In addition, there are some predefined properties that are not represented by
subelements or attributes of a container.

3.1 The value Property


Most containers have the notion of value ([XFA-Template], Template Overview, Form Structure, Containers,
Container Value). If a container is named in an XFA-SOM expression but not further qualified by a property name, the
reference is assumed to refer to the container's value. For example, in this calculation:
<field name="Total_Price" ...>
<calculate>
<script>Units * Unit_Price</script>
</calculate>
</field>

the simple XFA-SOM expression Unit_Price is actually a reference to the value of the container called Unit_Price.
For fields, the value is stored as a subelement of value:
<field name="Total_Price" ...>
<value><decimal>125.41</decimal></value>
...
</field>

For example, this implicit reference to the value of the field returns 125.41:
Total_Price

3.1.1 Other value properties


The value property described above is actually the property rawValue.
The rawValue property gives you back the unformatted value associated with the container. It is synonymous with
doing Total_Price.value.decimal for a numeric field named Total_Price, or Desc.value.text for a text
field named Desc. The use of rawValue is convenient because you don't need to know the type of the field in order to
access its value. You need to know the field is of type decimal prior to scripting Total_Price.value.decimal.
The formattedValue property gives you back the value of the container formatted according to the format
picture of the container as described in [XFA-Picture Clause]. For instance, the rawValue for Total_Price field
returns the decimal value 125.41 whereas the formattedValue property might return the string $125.41.

3.2 Accessing Properties that are Elements


Properties of a container can be represented as child elements of the container ([XFA-Template], Specification Notes,
How to Read an Element Specification, Properties). Properties can also contain properties. Properties are separated by a
dot (".") and appear to the right of a compound object name. For example, the XFA for a field container includes the
child element properties caption, and font; in turn, the caption and font properties have more child elements
properties:
<subform name="Detail" ...>
...
<field name="Sub_Total" ...>
<caption>
<font size="8pt" typeface="Minion">
<fill><color value="0,128,192"/></fill>
</font>
<value><decimal>Total Price</decimal></value>
...
</caption>
<font size="8pt" typeface="Minion">
<metrics/>
<fill>
<color/>
</fill>
</font>
...
</field>
...
</subform>

The compound object name is Detail.Sub_Total. Access the element properties of Sub_Total by appending the
element tag name:
Detail.Sub_Total.caption
Detail.Sub_Total.caption.font.fill.color
Detail.Sub_Total.font.metrics
Detail.Sub_Total.font.fill.color

3.3 Accessing Properties that are Attributes


Properties of a container can be represented as attributes of the container ([XFA-Template], Specification Notes, How
to Read an Element Specification, Properties). Like element properties, attribute properties are separated by a dot (".")
and appear to the right of a compound object name.
For example, the field container contains attribute properties x, y, w, and h and the subelement property caption.font
has size and typeface attribute properties:
<subform name="Detail" ...>
<field name="Sub_Total" y="105.13mm" x="11.99mm" w="40.64mm" h="10.6mm">
<caption>
<font size="8pt" typeface="Minion">
<fill><color value="0,128,192"/>
</fill>
</font>
<value><decimal>Total Price</decimal></value>
...

</caption>
<font size="8pt" typeface="Minion">
<metrics/>
<fill>
<color/>
</fill>
</font>
...
</field>
...
</subform>

These XFA-SOM expressions reference attribute properties of the field:


Detail.Sub_Total.x
Detail.Sub_Total.y
Detail.Sub_Total.caption.font.size
Detail.Sub_Total.caption.font.typeface

3.4 Name clashes


Name clashes can occur between container names and property names. XFA-SOM syntax resolves such ambiguities in
favor of the container. To access a property directly, previx it with the number sign, #.
This example contains a name clash between an attribute name and the name of a nested container.
<subform name="Detail" x="7.76mm" y="6.17mm" ...>
<field name="x" ...>...</field>
<field name="y" ...>...</field>
</subform>

The XFA-SOM expression:


Detail.x

returns the value of container which is the field named x.


The XFA-SOM expression:
Detail.#x

returns value of the attribute x on Detail or 7.76mm.


The next example, the Vendor subform contains a field with attribute name set to name. In addition, Vendor has a
property name that is set to Vendor.
<subform name="Vendor">
<field name="name">
<value>
<text>Ernest</text>
</value>
</field>
</subform>

The XFA-SOM expression:


Vendor.name

returns the value of the field named name, which is Ernest, because XFA-SOM resolves the name clash in favor of the
container.
To access the property called name, use .#:
Vendor.#name

returns the value of the property name on the Vendor container that is the string Vendor.
Note that this notation doesn't always resolve ambiguities. For example, PO.Detail still could refer to any one of the
subforms called Detail in the subform called PO. How ambiguities are resolved is explained in Multiply Occurring
Objects.
<subform name="PO" ...>
...
<subform name="Detail" ...>
...
</subform>
<subform name="Detail" ...>
...
</subform>
... more subforms named Detail ...
</subform>

10

4 Accessing Methods
An XFA-SOM expression allows access to the methods associated with a container. The syntax is described as part of
Accessors [XFA-FormCalc]. Methods are application-defined operators that act upon objects and their properties;
these operators are invoked like a function call in that arguments may be passed.
The object type determines the number and type of arguments in each method. Objects of different types support
different methods.
This XFA-SOM expression, which calls the method getValue(), returns the value of Sub_Total:
Sub_Total.getValue()

This XFA-SOM expression calls the method getAttribute() with a single parameter specifying the name of the
attribute to get:
Del_Instr.getAttribute("name")

11

5 Scoping Rules
The rules for object references described above are useful only if there is the concept of a context in which a name gets
resolved. In the Purchase Order Example, the field called Sub_Total contains a calculation script fragment that makes
reference to a field called Total_Price. The Purchase Order template is a hierarchical structure that contains several
fields called Total_Price at various locations and depths within the hierarchy. Scoping rules determine which one
gets used.
The remainder of this section describes the rules for how a container is located when referenced by name.

5.1 Containers are the Most Basic Units for Scoping


Containers (field, draw, subform, exclusion groups, and area) play a role in scoping. A script issued by a child element
of a container is thought of as having come from that container. There is no finer distinction of hierarchy for the source
of that script. When a script has an ancestry of multiple containers, it is the container that is the most immediate
ancestor that prevails.
In the following example, the results of the embedded script are applied to the enclosing container Sub_Total, which
is a field, and not to the non-container script or calculate elements. The embedded XFA-SOM expression is
evaluated according to scoping rules for the container Sub_Total:
<subform name="PO" ...>
...
<field name="Sub_Total"...>
<calculate>
<script>Sum(Detail[*].Total_Price)</script>
</calculate>
...
</field>
...
</subform>

5.2 Sibling Containers are Accessible


When resolving a reference, a container can see the names of its sibling containers. In the Purchase Order Example, the
PO subform contains sibling field elements (shown in green):

Because of the sibling relationship, the embedded script in the field Total_Price references Sub_Total and Tax by
name:
<field name="Total_Price" ...>
<calculate>
<script>Sub_Total + Tax</script>
</calculate>
...
</field>

12

5.3 Subforms and Exclusion Groups Form a Scoping Context


A subform or exclusion group is a container of containers. When these containers have a name attribute they form a
scoping context that prevents the siblings and ancestors of the container from directly accessing its children by name.
The children of the container can access each other directly by name as described above in Siblings are Accessible.
Subforms or exclusion groups without a name are an exception to this rule. For more information, see Anonymous
Subforms and Exclusion Groups are Transparent below.
Note that the template element also manages a scoping context for all the root-level subforms.
In the Purchase Order Example, a script attached to the Del_Instr field in the PO subform cannot access the field
Total_Price in the Detail subform directly by unqualified name.

This is intentional. The behavior of the scripts in the parent subform should not change when a child subform is added
that happens to have field names that match those used by the parent. The subform named Detail is in the same
scoping context as field Del_Instr, so an explicit reference to Detail.Total_Price provides access to the nested
Total_Price field. The compound expression is shown in red:
<field name="Del_Instr" ...>
<calculate>
<script>concat("Please pay ",Detail.Total_Price)</script>
</calculate>
</field>

5.4 Anonymous Subforms and Exclusions Groups are Transparent


An anonymous subform or exclusion group does not have a name attribute. An anonymous container does not hide its
children from its siblings. Therefore, an anonymous container does not provide a scoping context. The anonymous
container also does not prevent its siblings from being seen by its children. One can think of a anonymous container as
promoting its children to be its own siblings for name resolution.
The following example contains two anonymous subforms:

13

In the corresponding XML the two anonymous subforms have no name attribute. The Description field in the first
anonymous subform accesses the Units field in the second anonymous subform directly and accesses the
Total_Price field, which is a sibling of its anonymous subform parent, directly:
<subform name="Detail" ...>
<subform>
<field name="Item">...</field>
<field name="Description">
<calculate>
<script>concat("Please pay ", Total_Price, "for ", Units, " units.")</script>
</calculate>
</field>
</subform>
<subform>
<field name="Units">...</field>
<field name="Unit_Price">...</field>
</subform>
<field name="Total_Price">
<calculate>
<script>Units * Unit_Price</script>
</calculate>
</field>
</subform>

5.5 Areas are Transparent


Areas, whether named or unnamed, are containers that are transparent, meaning that they do not hide their children
from their siblings. They also do not prevent their siblings from being seen by their children. One can think of an area
as promoting its children to be its own siblings for name resolution. This happens recursively, so that all containers in a
hierarchy of areas can see each other by name.
In the following example, there are areas named ItemInfo and UnitInfo (highlighted in brown).

One can reference an area or its children in the same way: by unqualified name. In the example, there are two areas each
containing fields. A script attached to any one of these fields would be able to access any other field by name (subject to
multiple instance rules). For example, the field called Description in the area called Item_Info could access the
fields called Units in the area called Unit_Info without having to qualify the field names with the area name.
One can also use the area name as part of a larger, qualified reference to get at one of its children, thereby reducing the
chance of ambiguity. For example, from the context of field Total_Price, Unit_Info refers to the area called
Unit_Info and Unit_Info.Unit_Price refers to the field called Unit_Price in the area called Unit_Info.

14

5.6 Subform Ancestry


A subform manages a scoping context for its children, but also participates in the scoping context of its parent subform,
if there is one. In the Purchase Order Example, the Detail subform maintains a scoping context for the fields it
contains, and also participates in the scoping context maintained by the parent PO subform. As such, the subform
effectively participates in two scoping contexts. Scripts associated with the subform itself can access containers by name
in both contexts. Thus, the subform designer can script against objects within the subform and within the subform's
parent.
The following tree hierarchy (which is a subset of the Purchase Order Example) shows how an XFA-SOM expression in
a script associated with a subform can access both its siblings and children by unqualified name.

An XFA-SOM expression on the Detail subform can access the sibling of Detail by name:
<subform name="Detail" ...>
...
<calculate>
<script>Del_Instr</script>
</calculate>
...
</subform>

and also access a child of Detail by name:


<subform name="Detail" ...>
...
<calculate>
<script>Unit_Price</script>
</calculate>
</subform>

The subform's scoping context applies to its child containers: therefore, a child of the subform can access its siblings
and parent's siblings directly.
For example, the field Units can also access its sibling Unit_Price directly:
<field name="Units" ...>
...
<calculate>
<script>Unit_Price</script>
</calculate>
</field>

15

And Units can also directly access it parent's sibling Del_Instr:


<field name="Units" ...>
...
<calculate>
<script>Del_Instr</script>
</calculate>
</field>

And Units can also access its sibling Unit_Price directly:


<field name="Units" ...>
...
<calculate>
<script>Unit_Price</script>
</calculate>
</field>

For both subforms and containers within subforms, access is granted recursively all the way to the root template
element. Consequently, names accessible in the context of the root subform are accessible throughout the subform
hierarchy.
In summary, within a scoping context one can refer to:

All named containers within that context


All named containers within the that context's enclosing context
All named containers within the enclosing context's enclosing context, and so on all the way back to the root
context

A compound object name is required to access named containers within a child context, a sibling context, or a sibling of
an ancestor. This allows a form designer to create a form where local references prevail (i.e., a subform's internal field
references won't change when that subform is inserted into another). Yet, it still allows a subform access to fields in its
parent subform, which is very useful for accessing common fields. This is similar to variable scope in block-structured
programming languages.
When doing name resolution in a compound name, only the immediate scoping context is searched for a match. For
example, when doing name resolution on the XFA-SOM expression Detail.Total_Price, the nearest ancestor
scoping context for Detail is located first. Then Total_Price will be located only within the scoping context of
Detail. Therefore, the Total_Price that is a child of Detail is located, and not the Total_Price that is a sibling
of Detail.

5.7 Duplicate Names


In a subform hierarchy, the same container name can appear more than once. At a particular point in the hierarchy, a
particular name may be present on zero, one or more containers.
When a container references another by name, that name is resolved in the most immediate ancestral scoping context
that contains an occurrence of the name. It is a referencing error if there is no occurrence in any ancestral scoping
context.
XFA allows multiple instances of the same name to be accessible when a reference is made. This is extremely useful in
forms-processing applications. The means by which multiple occurrences of a name get resolved will be described later
in Multiply Occurring Objects. Finding the most immediate scoping context that yields a container of a particular name
16

may, in fact, yield several containers with that name. All occurrences of a name in the most immediate scoping context
that contains the name are accessible to the container that made the reference.
The existence of a scoping context with one or more objects of a particular name masks out instances of objects with
the same name in more distant ancestors. Therefore, once an match is found, matches are not sought in more distant
ancestors.
In this subset of the tree hierarchy from the Purchase Order Example:

A script attached to the field named Description in an instance of the subform Detail could make a reference to
Total_Price. This would be resolved in the subform Detail, because the name Total_Price is present there. The
field with the same name in the PO subform is masked from this vantage point. This script also accesses the Del_Instr
field in the parent subform by name.
<subform name="Detail">
<field name="Description" ...>
...
<calculate>
<script>concat("This is the ", Total_Price, ". Deliver to: ", Del_Instr)</script>
</calculate>
</field>
</subform>

Recall that a subform both manages its own scoping context and participates in its parent's context. If the subform
itself makes a reference to an object by name, it will be located first in the context managed by the subform. Only if the
name does not exist there, will it be located in the context managed by the subform's parent.
In any case, the field Total_Price that is a child of PO can be referenced using a compound object name.

17

6 Multiply Occurring Objects


In a form, it is often useful to have multiple objects of the same name. In the Purchase Order example, each Detail
subform contains an Item, Description, Units, Unit_Price, and Total_Price field. One would expect each
row of the purchase order to exhibit the same behavior, for example, the Total_Price field in the row is calculated as
being the product of Units and Unit_Price. In other words, the form exhibits behavior like that of many
spreadsheet applications.
Although a designer could create such a form without repeating field names, maintenance of the form would be a
headache, especially the process of adding rows. Ideally, adding new rows should be a copy-and-paste operation.
We will modify the Purchase Order Example to better explain how multiply occurring objects are handled.

6.1 Purchase Order with Single Detail


This is similar to the original Purchase Order Example, but contains a single Detail subform instead of a Detail
subform for each line in the table. Subforms are displayed in blue, fields in green.

18

The corresponding XML:


<template name="Static List Example">
<subform name="PO">
<field name="PO_Date" ...>...</field>

19

<field name="Req_No" ...>...</field>


<field name="Vendor_Code" ...>...</field>
<subform name="Vendor">
<field> name="name" ...>...</field>
<field name="address1" ...>...</field>
<field name="address2" ...>...</field>
<field name="address3" ...>...</field>
</subform>
<subform name="Detail">
<field name="Item"...>...</field>
<field name="Description"...>...</field>
<field name="Units"...>...</field>
<field name="Unit_Price"...>...</field>
<field name="Total_Price"...>...</field>
<field name="Item"...>...</field>
<field name="Description"...>...</field>
<field name="Units"...>...</field>
<field name="Unit_Price"...>...</field>
<field name="Total_Price"...>...</field>
... 3 more occurrences of Item, Description, Units, Unit_Price, Total_Price ...
</subform>
<field name="Sub_Total"...>...</field>
<field name="Tax"...>...</field>
<field name="Total_Price"...>...</field>
<field name="Del_Instr"...>...</field>
</subform>
</template>

6.2 References Relative to Current Occurrence


The most common use of multiply occurring names is to create spreadsheet-like behavior. Using the Purchase Order
with Single Detail example, to compute the value of the Total_Price field, the scriptwriter would attach a script to
each Total_Price field in Detail:
<subform name="Detail" ...>
...
<field name="Units" ...>...</field>
<field name="Unit_Price" ...>...</field>
<field name="Total_Price>
<calculate>
<script>Units * Unit_Price</script>
</calculate>
...
</field>
<field name="Units" ...>...</field>
<field name="Unit_Price" ...>...</field>
<field name="Total_Price>
<calculate>
<script>Units * Unit_Price</script>
</calculate>
...
</field>
...
</subform>

Array referencing syntax is not needed to specify which Units or Unit_Price field to use; the model is designed to
pick the correct one.
20

XFA-SOM treats multiply occurring fields of the same name as an array. When a multiply occurring field references
another without explicitly indicating an occurrence, XFA-SOM simply matches by index. For example, using the above
expression, the XFA-SOM expression on the second occurrence of Total_Price locates the second occurrence of
both Units and Unit_Price.
It is possible to design a form where the size of the array of referencing fields is not the same as the size of the array of
referenced fields. In such a case matching is still attempted by index number. So, if the reference falls within the range
of referenced fields, a match is found. If it falls outside, it is an error.
There is one exception to this rule. If a multiply occurring field makes reference to a singly occurring field with no
explicit occurrence indication, that single occurrence is always found. For example, all instances of the Total_Price
field might refer to a singly occurring Discount field.

6.3 Effect of Hierarchy on Multiply Occurring Object References


When a container refers to another by name, the reference may not be satisfied by an object in the same scoping context
(subform) as the container making the reference. It may be in the parent's context, grandparent's, the greatgrandparent's, and so on. When a container makes a reference by name (without explicit array referencing syntax) to an
object in an ancestral scoping context, the index of the ancestor that is a peer to the referenced container is used for
indexing if the referenced object occurs multiple times.
For example, consider the following tree view of a template:

Note: Array referencing syntax is 0 based.


Suppose that Detail[1].Amount[2] makes an unqualified reference to Summary. Summary exists in the scoping
context managed by the PO subform. That is an ancestral context of Amount, so Amount can access Summary by
unqualified name. The ancestor of Amount that is a peer to Summary is Detail. Occurrence [1] of Detail contains
the occurrence of Amount that made the reference. Therefore, the reference refers to Summary[1].
If the unqualified reference is itself a compound name, we walk back down the tree, using current occurrence
numbers. Continuing with the above example, if Detail[1].Amount[2] made an unqualified reference to
Summary.SummaryData, it would be resolved as Summary[1].SummaryData[2]. If the reference goes deeper than
21

the container making the reference, the first occurrence is located for those new depths. For example, a reference to
Summary.SummaryData.Total would resolve as Summary[1].SummaryData[2].Total[0].

XFA-SOM syntax allows for array referencing in compound names. Following are some examples of how various
references would be resolved from Detail[1].Amount[2]:
Reference
Summary[1]
Summary[0]
Summary.SummaryData[0]
Summary[0].SummaryData

Resolved as
Summary[1]
Summary[0]
Summary[1].SummaryData[0]
Summary[0].SummaryData[2]

22

7 Identifiers and Tokens for Accessing Nodes


XFA-SOM provides some predefined identifiers and tokens to make navigation of the forms hierarchy easier.
This table contains identifiers used in XFA-SOM expressions ([XFA-FormCalc], Lexical Grammar, Identifiers).
Identifiers
Identifier

Description

Refers to the current node. For example:


$.A

The above example finds the node A as an immediate child of the current node. Note that this is
different from the following example:
A

In this second example, the node A will also be found if it is an immediate child of the current node,
but if it does not exist there, then a search for the node A is made up the tree.
Appears only at the beginning of an XFA-SOM expression, i.e., before the first period.
!

Represents xfa.datasets, the first two nodes of the XFA Data DOM ([XFA Data Handling], Basic
Concepts, XFA Data DOM). For example:
!data.book.title

is equivalent to:
xfa.datasets.data.book.title

Appears only at the beginning of an XFA-SOM expression, i.e., before the first period.
$data

Represents the root node of the data model, xfa.datasets.data. For example:
$data.purchase_order.total

is equivalent to:
xfa.datasets.data.purchase_order.total

Appears only at the beginning of an XFA-SOM expression, i.e., before the first period.
$template

Represents the root node of the template model, xfa.template. For example:
$template.PO

is equivalent to:
xfa.template.PO

23

Identifiers
Identifier

Description
Appears only at the beginning of an XFA-SOM expression, i.e., before the first period.

$form

Represents the root node of the form model, xfa.form. For example:
$form

is equivalent to:
xfa.form

Appears only at the beginning of an XFA-SOM expression, i.e., before the first period.
This table describes tokens used in XFA-SOM expressions ([XFA-FormCalc], Lexical Grammar, Tokens).
Tokens
Token

Description

..

At any point after the first period, two dots ("..") can be used to search for descendant nodes (at any depth)
of a particular name. For example, the expression A..B means locate the node A (as usual), and find a
descendant of A called B. This is a depth-first search. Note that the ".." notation is equivalent to the XFASOM expression that uniquely represents the first node of the specified name.

Using the example tree above, the expression A..C is equivalent to A.B[0].C[0], because this node is
the first C node found. As a second example, A..C[*] returns the two leftmost C nodes, because, in this
example, A..C[*] is equivalent to A.B[0].C[*].
.#

Matches a property. This is useful if both a property and a container have the same name; the .# insures
that the property is accessed.
A.#B

.*

See also Name Clashes.


Selects all child nodes regardless of name. Cannot begin an XFA-SOM expression. For example, this
expressions selects all containers in the Detail subform:
Detail.*

[]

Array referencing syntax


24

Tokens
Token

Description
XFA-SOM treats the collection of accessible objects with the same name as an array. Array references are
zero-based.
In the Purchase Order with Single Detail example, one could think of the instances of the fields called
Units and Unit_Price as belonging to five element arrays:
Detail.Units[0]
Details.Unit_Price[3]

XFA-SOM supports the array syntax conventions specified here. Note that the XFA-SOM array referencing
syntax is not necessarily the same as the array referencing syntax of scripting languages.
One constructs an XFA-SOM array element reference by placing square brackets after a name and
enclosing within those brackets one of the following:
Index

Meaning

[n]

An absolute occurrence index number beginning at 0. An occurrence number that is out of


range is an error. Occurrence numbers in XFA-SOM syntax are not expressions. Only numbers
are valid. For example, if the following XFA-SOM expression is attached to the Detail subform:
Units[3]

the expression selects to the fourth occurrence of Units (circled in red).

25

Tokens
Token

Description
[+/-n] Indicates an occurrence relative to the occurrence of the object making the reference. Positive

numbers yield higher occurrence numbers while negative numbers yield lower occurrence
numbers. For example, if the following XFA-SOM expression is attached to the Detail subform:
Units[+1]

The expression selects the Units field whose occurrence number is two more than the
occurrence number of the container making the reference. For example, if this reference was
attached to Unit_Price[1] (underlined in blue), the reference would be the same as
Units[2] (circled in red).

If the computed index number is out of range, it is an error.


The most common use of this syntax is for locating the previous or next occurrence of a
particular field. For example, every occurrence of a field Unit_Price (except the first) might
use Unit_Price[-1] to get the value of the previous price field.
[*]

Indicates multiple occurrences of the object. The first named object is found, and all objects of
the same name that are siblings to the first are returned. Note that use of this notation results in
a collection of objects. For example, if the following XFA-SOM expression is attached to the
Detail subform:
Units[*]

The reference selects all objects with a name of Units that are siblings to the first Units found
(circled in red).

Using the tree for

26

Tokens
Token

Description

reference:
the following table shows which nodes are selected for each expression:
Expression

Resulting Nodes

A.B[*]

Both B nodes

A.B.C[*]

Two left-most C nodes. That's because A.B resolves to the first B node on
the left, and the C[*] is evaluated relative to that B node.

A.B[*].C

The first and the third C nodes from the left. A.B[*] resolves to both B
nodes, and the C is evaluated relative to both of those B nodes.
The second and fourth C nodes from the left. A.B[*] resolves to both B
nodes, and the C[1] is evaluated relative to both of those B nodes.

A.B[*].C[1]
A.B[*].C[*]

All four C nodes.

A.*

Both B nodes and both X nodes

A.X.*

Two left-most Y nodes.

27

8 Bibliography
THIS BIBLIOGRAPHY PROVIDES details on books and documents, from both Adobe Systems and other sources, that
are referred to in this specification.
Resources from Adobe Systems Incorporated
All of these resources from Adobe Systems are available on the Adobe Solutions Network (ASN) Developer Program
site on the World Wide Web, located at
http://partners.adobe.com/asn/developer/
Document version numbers and dates given in this Bibliography are the latest at the time of publication; more recent
versions may be found on the Web site.
The ASN can also be contacted as follows:
Adobe Solutions Network
Adobe Systems Incorporated
345 Park Avenue
San Jose, CA 95110-2704
(800) 685-3510 (from North America)
(206) 675-6145 (from other areas)
acrodevsup@adobe.com
[Adobe Patent Clarification Notice]
Adobe Patent Clarification Notice. Available on the Legal Notices page of the ASN Developer Program Web
site.
[XFA-Data Binding]
Data Binding Specification 2.0, Adobe Systems Incorporated, October 2003.
Available from http://partners.adobe.com/.
[XFA-Data Handling]
Data Handling Specification 2.0, Adobe Systems Incorporated, October 2003.
Available from http://partners.adobe.com/.
[XFA-FormCalc]
FormCalc Specification 2.0, Adobe Systems Incorporated, October 2003.
Available from http://partners.adobe.com/.
[XFA-Picture Clause]
Picture Clause Specification 2.0, Adobe Systems Incorporated, October 2003.
Available from http://partners.adobe.com/.
[XFA-Template]
Template Specification 2.0, Adobe Systems Incorporated, October 2003.
Available from http://partners.adobe.com/.

28