XFA Specification
Chapter 16, Config Specification
The Configuration Data Object Model
677
The actual location of the configuration document (or documents) is variable. XFA provides a convenient
mechanism for packaging XML data (“XDP
which might be used to bundle
configuration options with the template and other relevant material. However, XFA applications are free to
use other mechanisms, such as environment variables and command-line parameters, instead of or in
addition to XDP. This specification is limited to the setting of configuration options via XML documents
and scripts.
The Configuration Data Object Model
The Configuration Data Object Model (Configuration DOM) encapsulates the XFA configuration
information and provides standard interfaces to it. The Configuration DOM contains data objects
organized in a tree structure. The configuration tree is itself a branch within a larger XFA tree.
The “config” element and the standard contents shown above must belong to the namespace
“http://www.xfa.org/schema/xci/1.0/” which is known as the XCI namespace. Custom elements may
belong to the XCI namespace but are not required to.
Defaults
Conceptually the Configuration DOM exists before any configuration document is loaded. The
Configuration DOM must initialize all option values to their default values at startup. Options that require a
keyword value must be initialized to the values shown in the corresponding elements of the above
skeleton. Options that do not require keyword values must be initialized to the empty string.
When the XFA application loads the configuration DOM from a configuration document, if a particular
element is not present in the configuration document, the associated option must retain its preexisting
value.
Most of the default values cause the associated option to adopt safe behavior. The only exceptions are the
“uri” elements which supply the locations for the data and template documents; the XFA application may
declare a fatal error if either or both of these options is set to the empty string when the time comes to
load the associated document. As an alternative it may fall back on some other mechanism to locate the
required document.
Scripting Interface
The Configuration DOM is part of a larger tree that holds all exposed XFA objects. The single large tree
makes it possible to refer to XFA objects using a unified format known as a Scripting Object Model (SOM)
expression. The grammar of SOM expressions is described in
“Scripting Object Model” on page 81.
Briefly,
an expression consists of a sequence of node names separated by periods (“.” characters). Starting from
some point in the XFA tree, each successive name identifies which child of the current node to descend to.
The root of the Configuration DOM must be a child of the root
xfa
node. Hence, the
config
node itself is
xfa.config
. Assuming the application Name is “myapp”, the node representing the
attributes
element would be referenced by the SOM expression
xfa.config.myapp.data.attributes
.
In addition, SOM expressions must recognize the short-form “$config” as equivalent to
xfa.config
. Thus
for example the “attributes” element mentioned in the preceding paragraph could be referenced as
$config.myapp.data.attributes
.
The scripting interface must make it possible for user-supplied scripts to inspect and modify the contents
of the Configuration DOM. It is not responsible for guaranteeing that modifying the value of a particular
option will have any effect. In particular, many options have an effect only during a particular phase of