domObj.appendInstance

(Merge only)

Dynamically append another instance of an existing, Allow Multiple child Pane. Prior to 3.1.001.02, this applied to panes only. As of 3.1.001.02, it applies to rows as well.

Syntax

domObj.appendInstance()

(As of 3.0.003.15) domObj.appendInstance([paneName])

Returned Value

The domObj pointer of the pane that was created. null if something went awry.

Parameters

As of 3.0.003.15, a Pane name can be supplied. If supplied then that Pane will be cloned from the Form Template DOM, i.e. not requiring an existing Pane instance in the Document DOM.

Description

For all but some minuscule percentage of the time, the merging of data with a form design will automatically produce the exact number of instances you need. However, we have an existence proof that a need to script the creation of additional Panes does exist. Note that one instance of the Pane must exist*. It can be mandatory and invisible, but it must exist. That Pane is cloned and appended to the current set of the parent's child Panes.

Example

Terms and Conditions (T&C) clauses. Having them in your data stream is quite a bit yucky. Having them in your form design is equally yucky. Yet they do vary. And significantly, really significantly, they are not items that are the responsibility of the form designer, nor should the constructor of the data want to embed such, other-department things in the data.

So... imagine a folder that is maintained independently by that 'other-department'. It contains RTF files with the precisely desired wording of each clause. As life marches on, the number of clauses varies. Do let's keep our form designs and data streams immune from that.

One can write a script to enumerate all the RTF files in the designated T&C folder. Now you just need sufficient Panes to put them in.

clausePath = $F + "/Clauses";
clauses = clausePath + "/*.rtf";
itemNumber = 0;
_file.findClose();                      // Start a fresh file scan
for (fn = _file.findNext(clauses); fn; fn = _file.findNext(clauses)) {
	itemNumber++;
	r = this.Clause.appendInstance();       // Get another pane instance to hold this clause
	r.fileName._value = fn;                 // Hidden field with the filename in it, fwiw
	r.itemText._value = itemNumber + ".";   // Number the clauses as we go
	r.clauseText._value = "[@" + fn + "]";  // The value just points to the rtf file
	r._visible = true;
}
_file.findClose();                      // Be kind to mankind, clean up after yourself

Form Explorer View