Add Trace to Form Script

I continue to spend time playing with the prototype macro capability found in Designer 9 (ES2).  I have a new sample that uses it, but of course before showing you, I need to reiterate that the macro stuff is still an unsupported trial feature.

I wanted to do something to further help people debug their form script.  The usual way this happens today is that you sit down and add console.println() commands to the various scripts that run.  There are a few drawbacks to this mode of debugging:

  • It is tedious to add the debug/trace statements
  • It is not always clear which scripts need to have trace added
  • If you generate too much output, the console window fills up and stops showing content
  • FormCalc scripts cannot access the console object
  • Dumping large amounts of content to the console slows form execution considerably

To help matters along, I have written a macro that will modify scripts in your form and automatically add trace statements.  The injected code does the following:

  • Adds a top-level script object (scTrace) for collecting trace statements
  • scTrace stores trace statements in a JavaScript array — so that the size is not limited by the console
  • Adds a pre-print event that allows the array of trace statements to be dumped to a file
  • Adds a "full" event script to the root subform that can be used with execEvent() to emit strings from FormCalc scripts (this technique first introduced in this blog entry)

As an example, the before and after for a specific JavaScript looks like:

Before:

var vTarget = xfa.event.target;
if (vTarget.className === "field") {
     vTarget.fillColor = "220,220,255";
}

After:

scTrace.traceContext("enter:", this);
var vTarget = xfa.event.target;
if (vTarget.className === "field") {
     vTarget.fillColor = "220,220,255";
}

For FormCalc the result is a bit more verbose:

Before:

price * units

After:

;scTrace.trace
xfa.event.fullText = "calculate"
xfa.event.newText = $.somExpression
$form.#subform.execEvent("full")
price * units

Note that when you use this debugging technique you must not leave this script in your production forms.  It adds too much overhead.  When you want to trace/debug your form, follow these steps:

  1. Save a copy of your form
  2. Add trace to the copy
  3. Run the copy in Acrobat (not Reader)
  4. When you want a trace dump, print the form.  The pre-print event fires and prompts you to save the trace (when trace has been saved, cancel the print)
  5. debug and migrate changes/fixes back to the original document

The actual macro is here.  You need to rename it to have a .js suffix and put it in a subdirectory under the Scripts directory in your Designer install (see detailed instructions in the original blog entry).

Here is a sample form where trace has been injected.

I’ve found this tracing technique to work well in cases where form performance may be impacted by lots of events and scripts.  Especially in cases where there are dependency loops (see the discussion under "Dependency Loops" in this blog entry).

Note that the macro does not add trace to the indexChange event.  I ran into a scenario where this combination produced some bad behavior, so I elected to exclude that trace.  Hopefully this problem gets sorted out in the next version of Designer.