Problem
JavaScript objects allow you to reuse functionality across your forms but there
are a some tricks to getting them to work in the Adobe Acrobat / Reader environment.
Solution
There a a couple of ways to create objects in JavaScript. Using the new operator
and a constructor function, or using the object literal syntax. The new operator
has some advantages as it allows the developer to enforce an initialisation script
be executed and is easily understood by programmers coming from languages that support
classes. Using the literal syntax might require a static method to create the object
or an 'initialise' method ( or 'start' method in the sample below ). But using the
new operator requires a work around that is well described in John Brinkman's blog,
http://blogs.adobe.com/formfeed/2009/09/script_objects_deep_dive.html. This is an
alternative that might fit some situations and uses the literal syntax to create
JavaScript objects defined within an XFA script object.
Detailed explanation
This sample defines an object that can be used for measuring elapsed time, a StopWatch,
and can be used like;
var sw1 = StopWatch.stopWatch("StopWatch1");
sw1.start();
for (var i=0;
i<1000; i++) {} // or something we want to measure
sw1.stop();
sw1.println();
This will output a message on the console that looks like;
StopWatch1:Time elapsed
127ms
Or using a static method to construct the object and achieve the same result;
var sw1 = StopWatch.startNew("StopWatch1");
for (var i=0;
i<1000; i++) {} // or something we want to measure
sw1.stop();
sw1.println();
The script object is called StopWatch and the function defined within it is called
stopWatch, but note that we do not use the new operator to create it. The stopWatch
function returns a inner object that retains access to the variables and functions
of stopWatch without exposing them to the calling code. This is called a closure
and more information about closures and nested functions is available at
https://developer.mozilla.org/en/JavaScript/Reference/Functions_and_function_scope/#Nested_functions_and_closures.
This means there is no way outside code can access the variables
startTime,
elapsed,
isRunning or the function
getElapsedTime.
form1.#variables[0].StopWatch - (JavaScript, client)
function stopWatch(label){
/**
* Private variables used internally by the StopWatch
object.
*/ var
startTime = 0;
var elapsed = 0;
var isRunning =
false;
/**
* A private helper function to return the number
of milliseconds since the
* StopWatch was started.
*/ function
getElapsedTime()
{
return
Date.now() - startTime;
}
/**
* The StopWatch object as visible to other form code.
*/ return
{
/**
* Determines if a StopWatch
is running
* @return {boolean} true
is the StopWatch is running otherwise false.
*/
getIsRunning: function IsRunning()
{
return isRunning;
},
/*
* Returns the total time since
the StopWatch was first started.
* @return {int} The total number
of elapsed milliseconds.
*/
getElapsed: function getElapsed()
{
var result = elapsed;
if (isRunning)
{
result += getElapsedTime();
}
return result;
},
/*
* Starts (or continues), measuring
elapsed time.
*/
start: function start()
{
if (!isRunning)
{
isRunning = true;
startTime = Date.now();
}
},
/*
* Stops (or pauses) measuring elapsed
time.
*/
stop: function stop()
{
if (isRunning)
{
elapsed += getElapsedTime();
isRunning = false;
}
},
/*
* Stops the StopWatch and resets
the elapsed time to zero.
*/
reset:function reset()
{
elapsed = 0;
isRunning = false;
startTime = 0;
},
/*
* Outputs the elapsed time to the
console.
*/
println: function println()
{
console.println(util.printf("%sTime elapsed %,0dms",
(label === undefined) ? "" : label +
":",
this.getElapsed()));
}
}
}
This approach would allow me to pass in an argument to stopWatch and have
different objects returned, perhaps one measuring in decimal time, or more usefully
in a real example having different objects returned depending on a country id passed
in that provided appropriate calculations, validations and initialisations. Creating
objects this way is known as the factory pattern.
I have often used the StopWatch code when experimenting with individual parts of
my form that are not performing fast enough. But I have also modified John Brinkman's
trace macro
http://blogs.adobe.com/formfeed/2010/06/add_trace_to_form_script.html to
add code to all script events in a form. More details of macros and how to install
them can be found in one of his earlier blogs,
http://blogs.adobe.com/formfeed/2010/01/designer_es2_macros.html,
but it should be as simple as creating a directory
C:\Program Files (x86)\Adobe\Adobe
LiveCycle Designer ES2\Scripts\AddExecutionTimes, copy the AddExecutionTimes.js
file to the folder and restart Designer. Once restarted there will be an option
under Tools ... Scripts called AddExecutionTimes.js. If there is any problem running
the macro then the messages should be displayed on the Log tab of the Report window.
Make a copy of the form before running this macro as I don't have a macro to remove
the StopWatch code that gets inserted. Now when you preview your form messages will
appear with the form object somExpression, the event name and the elapsed time,
something like;
xfa[0].form[0].form1[0].#subform[0].TextField1[0].#calculate:Time elapsed 92ms
xfa[0].form[0].form1[0].#subform[0].Table1[0].Row2[0].DecimalField1[0].#calculate:Time
elapsed 58ms
xfa[0].form[0].form1[0].#subform[0].Table1[0].Row2[1].DecimalField1[0].#calculate:Time
elapsed 60ms
xfa[0].form[0].form1[0].#subform[0].Table1[0].Row2[2].DecimalField1[0].#calculate:Time
elapsed 60ms
xfa[0].form[0].form1[0].#subform[0].Table1[0].Row2[3].DecimalField1[0].#calculate:Time
elapsed 92ms
xfa[0].form[0].form1[0].#subform[0].Table1[0].Row2[4].DecimalField1[0].#calculate:Time
elapsed 86ms
xfa[0].form[0].form1[0].#subform[0].TextField1[0].#validate:Time elapsed 57ms
xfa[0].form[0].form1[0].#subform[0].Button1[0].event__click:Time elapsed 2,565ms
The StopWatch object has been modelled after the .net system.diagnostics.stopwatch
object that I have found useful, but that one uses performance counters, this one
uses the JavaScript date object so all timings are just indicative, you may have
to run your tests a number of times to get a more accurate measure and minimise
the number of other processes running on your machine. But hopefully this will point
to parts of your form that are chewing up the most time and help identify candidates
for optimisation.
StopWatch.pdf is a sample with the macro already run, when opened the
console will be displayed with initialisation messages displayed, as you interact
with the form more messages will be displayed.
StopWatch.xdp a script fragment containing the StopWatch object.
AddExecutionTimes.js the macro for adding StopWatch code to all of your
events.
