Transactional XFA Data DOM Structure

JavaScript events can create, clone, rename, attach, reorder, and detach native Data DOM elements, with immediate script reads and transaction-wide native persistence

const record = xfa.record;
const value = xfa.datasets.createNode("dataValue");
value.name = "amount";
value.value = "42";
record.nodes.append(value);
const retained = value.clone(false);
record.nodes.remove(value);
record.nodes.insert(value, record.nodes.item(0));

Supported operations

xfa.datasets.createNode(className, name = "", namespace = "") creates an unattached dataGroup or dataValue; qualified names require a nonempty namespace URI

node.clone(recursive = true) creates an unattached Data DOM copy with fresh identities; false excludes child nodes while retaining the element's own metadata and value

node.name is writable for Data DOM elements and preserves namespace, sibling order, descendants, and retained aliases; an unnamed construction must receive a valid local name before attachment

node.nodes.length, item(index), and namedItem(name) read the live ordered element children; item and namedItem return null when no child matches

nodes.append(node) and nodes.insert(node, before) transfer the same object into the owner's children; insert(node, null) appends

nodes.remove(node) detaches a direct child while keeping its object and subtree available to retained aliases and later reattachment

xfa.record returns the current first record under the Data DOM data root and updates after structural edits

Identity, XML, and bindings

A script object can retain a node, descendant, or owning child collection across events; live aliases resolve the same native objects after attachment, detachment, rename, and rollback

loadXML and saveXML work on newly created and moved elements, including descendants imported and then moved during the same event

Stable native identities keep imported descendant aliases from silently resolving a different child after positional changes

Inherited attribute namespaces, explicit empty default namespace resets, comments, processing instructions, CDATA, and Unicode values survive clone, move, save, and reload

Form bindings refresh after structural changes, and values written through newly attached data nodes reach the corresponding repeated form instance without changing another instance

Transactions and limits

Invalid classes, XML names, sibling references, cycles, and foreign nodes fail before that individual operation changes the live script graph

An uncaught script error, native apply failure, cancellation, operation cap, or elapsed-time limit restores the complete event, including attached and detached nodes, binding values, retained aliases, lexical script-object state, and journal state; the same runtime can then retry

Structural nodes and detached trees share native node, depth, and UTF-8 byte caps; the original script transaction deadline applies to JavaScript and native changes together

PDF consumption

Save the runtime to XDP and pass those bytes to HPDFXFAWriteHeadlessPDF to create actual native PDF fields and appearances from the changed data bindings

TXFAHeadlessPDFOptions.Editable = False creates read-only native fields with appearances; that setting does not flatten them

Current coverage

This page describes Data DOM edits; transactional form tree scripting provides supported live form creation, cloning, insertion, removal, and native PDF consumption

General template editing, complete choice subform-set processing, and the full XFA node-class schema remain separate capabilities

Independent query node collections · Native structural graph API · XFA widget runtime