TechNote

Modifying sourceSet in XFA 2.5+ Forms

Because you might not know for certain if or when unexpected security exceptions might occur in a form's workflow after it is certified and/or rights-enabled for Adobe Reader, you should work with a cloned in-memory copy of the original SourceSet model instead of directly using the original SourceSet model.

Cloning Form Nodes

The solution is to use the

clone(deep)

method on the node that defines the particular data connection that you want to modify within the SourceSet model, and to ensure that your script keeps using the clone instead of the actual definition. The clone(deep) method accepts a Boolean parameter that, when set to 1 (or true), will clone the node and all of its children (which is what you want to do; otherwise, you will only get a shell instead of the full data connection) and return a reference to the in-memory copy.

For example, consider the following script taken from the Data Drop Down List object on the Custom tab in the Library palette:

var oDB = xfa.sourceSet.nodes.item(nIndex);

...

// Search node with the class name "command"

var nDBIndex = 0;

while(oDB.nodes.item(nDBIndex).className != "command")

nDBIndex++;

oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayBOF", "bofAction");

oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayEOF", "eofAction");

Notice that the script first obtains a reference to a data connection node located within the original sourceSet model, and then modifies some of its properties. This means that an XFA 2.4 form that is opened in Acrobat 8.0 or later will function properly prior to certification or rights-enabling for Adobe Reader, although it may stop functioning correctly if the form is certified and/or rights-enabled for Adobe Reader. However, in an XFA 2.5 form, it will immediately fail and display a security exception, because Acrobat 8.0 or later determines that the sourceSet model may eventually become protected and protects it from the start.

To apply the cloning technique to this script, you need to change the line that accesses the sourceSet model:

For JavaScript:

var oDB = xfa.sourceSet.nodes.item(nIndex).clone(1);

For FormCalc:

var oDB = Ref(xfa.sourceSet.nodes.item(nIndex).clone(1))

Notice the clone(1) method appended to the end of the statement. At that point, oDB receives a reference to a copy of the original sourceSet model, which you can modify regardless of the forms certification or Adobe Reader rights-enabled status. You do not need to modify the rest of the script at all.

Keep in mind that you could just as easily store the cloned data connection node in a form variable or in a variable that is defined in a Script Object, such that you can reference it again if you make modifications that you want to persist when the form is opened in Acrobat.