Native XFA Absent Property Creation
Unit: HPDFXFAEventScript, integrated through HPDFXFARuntime and HPDFXFA
Event access
JavaScript form nodes expose getElement(className, occurrence=0); an absent supported property is created with schema defaults, and repeated access returns the same live property handle
Direct property access, such as field.font or draw.para, creates occurrence zero when the supported child is absent
const label = xfa.form.resolveNode("main.row[1].label");
const font = label.getElement("font", 0);
font.typeface = "Helvetica";
font.size = "18pt";
font.fill.color.value = "0,128,255";
label.para.hAlign = "right";
label.border.getElement("edge", 3).thickness = "0.25pt";The occurrence argument must be a non-negative integer within schema cardinality; requesting edge[3] creates the preceding missing edge occurrences, each with its own schema defaults
Supported creation paths
| Parent class | Supported children and maximum occurrences |
|---|---|
| field | assist, bind, border, calculate, caption, desc, extras, font, format, keep, margin, para, traversal, ui, validate and value: one each; items: two |
| draw | assist, border, caption, desc, extras, font, keep, margin, para, traversal, ui and value: one each |
| ui | extras and picture: one each; one mutually exclusive widget choice as described in UI Property Overrides |
| passwordEdit, choiceList and checkButton | border, extras and margin: one each |
| font | extras and fill: one each |
| para | hyphenation: one |
| border | edge and corner: four each; extras, fill and margin: one each |
| caption | extras, font, margin, para and value: one each |
| margin | extras: one |
| fill | color and extras: one each; linear, pattern, radial, solid and stipple: one mutually exclusive child |
| textEdit | border, comb, extras and margin: one each |
| edge and corner | color and extras: one each |
Unlisted child classes return null from getElement; invalid occurrences and conflicting fill choice children fail the event transaction
Creation of metadata containers does not execute newly stored scripts; event, calculate and validate behaviour follows the existing runtime execution model
Native persistence and identity
Creation and subsequent writes publish actual native form-packet nodes beneath the selected repeated occurrence; the template and other occurrences retain their original values
The next event rebuilds form-only property bindings from the saved native form packet, so both direct access and SOM resolution observe the created hierarchy
Retained script-object references continue to address the native property after successful transactions and instance insertion; writing a reference after its instance is removed fails and restores the transaction
Cloning a repeated prototype also clones its form-only property structure, using schema defaults for new property attributes rather than another occurrence's overrides
Engine failures and native mutation failures restore native bytes, property nodes, datasets, script state and instance order; creation shares node, operation, depth, byte and value budgets
Effective consumers and saved PDF output
Field and rich draw consumers read created font, fill/color, paragraph and border/edge properties during actual layout and flattening; subsequent events and saved XDP reloads preserve these values
With THotPDF.AutoFormAppearances=True, XFA text fields generate their native appearance after the effective style is applied, including supported standard font families, point size, text colour, alignment and solid border colour and width
AutoFormAppearances remains an explicit document option; its default False continues to rely on reader appearance generation
Creation and formatting consumer coverage are separate: additional value child classes and widget schemas, general schema classes, property removal/reparenting, richer widget text and Unicode appearance embedding remain active implementation targets
Related APIs
Native XFA Property DOM, XFA Property Schema Defaults, TXFAEventAction and TXFAEventBinding