Previous Next
all variables with “xyz_”. This will prevent collisions with other persistent global variable
names throughout the documents.
Note that global variables that are persistent are recorded in the plug-in level glob.js file upon
application exit and re-loaded at application start. See the section on Plug-in folder level scripts
for more details.
Acrobat Forms - JavaScript Object Specification 51
this Object
In JavaScript the special keyword “this” refers to the current object. In Acrobat Forms the
current object is defined as follows:
• In an object method, it is the object to which the method belongs.
• In a constructor function, it is the object being constructed.
• In a function defined at the Plug-in folder level it is undefined. It is recommended
that calling functions pass the document object to any function at this level that
needs it.
• In a Document level script or Field level script it is the document object and
therefore can be used to set or get document properties and functions.
For example, assume that the following function was defined at the Plug-in folder level:
function PrintPageNum(doc)
{ /* Print the current page number to the console. */
console.println(“Page=” + doc.page);
}
The following script outputs the current page number to the console (twice) and then prints the
page:
PrintPageNum(this); /* Must pass the document object. */
console.println(“Page=” + this.pageNum); /* Same as the previous call. */
this.print(false, this.pageNum, this.pageNum); /* Prints the current page. */
Variable and Function Name Conflicts
Variables and functions that are defined in scripts are parented off of the this object. For
example:
var f = this.getField(“Hello”);
is equivalent to
this.f = this.getField(“Hello”);
with the exception that the variable “f” can be garbage collected at any time after the script is
run.
If a script uses a name that conflicts with a document level property or method and the this
object is the current document then a run-time error will result: Invalid or unknown property,
set not possible.
The following script fragment will generate such an error:
var pageNum = this.pageNum;
To avoid such an error, rename your variables and functions to avoid conflict:
var pNum = this.pageNum;
Acrobat Forms - JavaScript Object Specification 52
Util Object
The Util Object is a static JavaScript object that defines a number of utility methods and
convenience functions for string and date formatting.
Util Object Methods
printf
Parameters: cFormat
Returns: cResult
This method will format one or more values as a string according to a format string. This is
similar to the C function of the same name.
printx
Parameters: cMask, …
Returns: cResult
This method formats a source string according to a masking string. Valid masking values are as
follows:
Value Effect
? Copy next character.
X Copy next alphanumeric character, skipping any others.
A Copy next alpha character, skipping any others.
9 Copy next numeric character, skipping any others.
* Copy the rest of the source string from this point on.
\ Escape character.
> Uppercase translation until further notice.
< Lowercase translation until further notice.
= Preserve case until further notice (default).
To format a string as a U.S. telephone number, for example, use the following script:
var v = "aaa14159697489zzz";
v = util.printx("9 (999) 999-9999", v);
console.println(v);
Acrobat Forms - JavaScript Object Specification 53
printd
Parameters: cFormat, date
Returns: cResult
Use this method to format a date according to a format string. Valid string format values are as
follows:
String Effect Example
mmmm Long month September
mmm Abbreviated month Sept
mm Numeric month with leading zero 09
m Numeric month without leading zero 9
dddd Long day Wednesday
ddd Abbreviated day Wed
dd Numeric date with leading zero 03
d Numeric date without leading zero 3
yyyy Long year 1997
yy Abbreviate Year 97
HH 24 hour time with leading zero 09
H 24 hour time without leading zero 9
hh 12 hour time with leading zero 09
h 12 hour time without leading zero 9
MM minutes with leading zero 08
M minutes without leading zero 8
ss seconds with leading zero 05
s seconds without leading zero 5
tt am/pm indication am
t single digit am/pm indication a
\ use as an escape character
To format the current date in long format, for example, you would use the following script:
var d = new Date();
console.println(util.printd("mmmm dd, yyyy", d));
Acrobat Forms - JavaScript Object Specification 54
scand 4.0
Parameters: cFormat, cDate
Returns: date object
This method converts the supplied date, cDate, into a JavaScript date object according to rules
of the supplied format string, cFormat. cFormat uses the same syntax as found in printd. This
routine is much more flexible than using the date constructor directly.
/* Turn the current date into a string. */
var cDate = util.printd("mm/dd/yyyy", new Date());
console.println("Today’s date: " + cDate);
/* Parse it back into a date. */
var d = util.scand("mm/dd/yyyy", cDate);
/* Output it in reverse order. */
console.println("Yet again: " + util.printd("yyyy mmm dd", d));
Note: Given a two digit year for input, scand resolves the ambiguity as follows: if
the year is less than 50 then it is assumed to be in the 21st century (i.e. add
2000), if it is greater than or equal to 50 then it is in the 20th century (add
1900). This heuristic is often known as the Date Horizon.
Acrobat Forms - JavaScript Object Specification 55
Implementation Considerations
JavaScript Locations and Loading
JavaScripts work with Acrobat Forms on a variety of levels: the plug-in level, document level,
and field level. These levels restrict the type of processing that can occur and are loaded at
different times.
Plug-in folder level
JavaScripts can work as individual files with the “.js” extension. The Acrobat Forms plug-in
looks for these files on the UNIX platform in the Acrobat plug-ins folder. On the Apple
Macintosh and Windows platforms, the files are in a subfolder of the plug-ins/Acroform folder
called JavaScripts. Variables and functions that might be generally useful to the application
should be kept at the plug-in level.
There are some restrictions when writing plug-in level scripts particularly with respect to the
this Object.
The standard Acrobat Forms implementation comes with two plug-in level files: Aform.js,
which contains built-in pre-canned functions and AFString.js, which contains the language
dependent strings needed by Aform.js.
The file glob.js is programmatically generated and contains cross-session application
preferences set using the global object’s setPersistent method.
4.0 If the file Config.js is present this file can be used to customize the look of the viewer
by removing toolbar buttons and menu items (see the application methods hideMenuItem and
hideToolbarButton).
The plug-in level scripts are loaded in the following order: Config.js (if it exists), AFString.js,
AForm.js, glob.js (if it exists), and then all other .js files in no particular order.
Document level
By using the Adobe Acrobat menu item Tools->Forms->Document Scripts…, the user can add,
modify, or delete document level scripts. These scripts should be function definitions that are
generally useful to the document but are not applicable outside the document. Document level
scripts are executed after the document has opened and after the plug-in level scripts are
loaded. Document level scripts are stored within the PDF document. Therefore, the forms
programmer should make every effort to package scripts as effectively as possible.
Acrobat Forms - JavaScript Object Specification 56
Field level
The user can add scripts to a form field definition using a dialog box in the form editing tool.
(see Event Processing section below). These scripts are executed as the events occur (e.g.
mouse up or calculate). Scripts that are field specific should be created at this level. Usually
these scripts validate, format, or calculate field values.
Unlike plug-in folder scripts, document level and field level scripts are stored within the PDF
document and therefore the forms programmer should make every effort to package his scripts
as effectively as possible (e.g. code reuse) at the various levels for performance and file size
reasons.
Form Field Hierarchies
Form fields typically have names like FirstName, LastName, etc. This naming convention is
referred to as flat names. For many form applications, this flat hierarchy of names is sufficient
and works well. The problem with using flat names is that there is no association between the
fields.
Form field names can be more useful by creating a hierarchal structure. For example, if we
change FirstName to Name.First and LastName to Name.Last we form a tree of fields. The
period (‘.’) separator used in Acrobat Forms and denotes a hierarchy shift. The Name portion
of these fields is the parent, and First and Last become the children. While there is no limit to
the depth a hierarchical name can be constructed it is important that the hierarchy remain
manageable.
This hierarchy can be useful in a number of ways. It can speed up authoring and ease
manipulation of groups of fields in JavaScript. In addition, a form field hierarchy can improve
the performance of forms applications when there are many fields in the document.
Form Field Hierarchies with JavaScript
Using our original flat names FirstName, MiddleName and LastName, imagine that we want to
change the background color of these fields to yellow (to indicate missing data, or emphasize
an important point). We would need two lines of JavaScript code for each field:
var name = this.getField("FirstName");
name.fillColor = color.yellow;
name = this.getField("MiddleName");
name.fillColor = color.yellow;
name = this.getField("LastName");
name.fillColor = color.yellow;
With our hierarchy of Name.First, Name.Middle and Name.Last above (and perhaps,
Name.Title if used), we can change the background color of these fields with just two lines of
code instead of six:
Acrobat Forms - JavaScript Object Specification 57
var name = this.getfield("Name");
name.fillColor = color.yellow
When using this hierarchy within a JavaScript, remember you can only change appearance
related properties of the parent field and that appearance changes propagate to all children.
You cannot change the field’s value. For example if you try the following script:
var name = this.getField("Name");
name.value = "Lincoln";
the script will fail. Name is considered a parent field. You can only change the value of
terminal fields (i.e. a field that does not have children like Last or First). The following script
executes correctly:
var first = this.getField("Name.First");
var last = this.getField("Name.Last");
first.value = "Abraham";
last.value = "Lincoln";
Working With The Date Object
This section discusses the use of Date objects within Acrobat. The reader should be familiar
with the JavaScript Date object and the Util Object functions that process dates. JavaScript Date
objects are actually an object containing both a date and time. All references to date in this
section refer to the date-time combination.
Note: All date manipulations in JavaScript, including those methods that have
been documented in this specification are Year 2000 (Y2K) compliant.
Converting a Date to a String
Acrobat Forms provides several date related methods in addition to the ones provided by the
JavaScript Date object. These methods are the preferred method of converting between Date
objects and strings. Because of Acrobat Forms' ability to handle dates in many formats, the
Date object does not always handle these conversions correctly.
To convert a Date object into a string, the printd method of the Util Object is used. Unlike the
built-in conversion of the Date object to a string, printd allows an exact specification of how
the date should be formatted.
/* Example of util.printd */
var d = new Date(); /* Create a Date object containing the current date. */
/* Create some strings from the Date object with various formats with
** util.printd */
var s1 = util.printd("mm/dd/yy", d);
Acrobat Forms - JavaScript Object Specification 58
var s2 = util.printd("yy/m/d", d);
var s3 = util.printd("mmmm dd, yyyy", d);
var s4 = util.printd("dd-mmm-yyyy", d);
/* print these strings to the console */
console.println("Format mm/dd/yy looks like: " + s1);
console.println("Format yy/m/d looks like: " + s2);
console.println("Format mmmm dd, yyyy looks like: " + s3);
console.println("Format dd-mmm-yyyy looks like: " + s4);
The output of this script would look like:
Format mm/dd/yy looks like: 01/15/99
Format yy/mm/dd looks like: 99/1/15
Format mmmm dd, yyyy looks like: January 15, 1999
Format dd-mmm-yyyy looks like: 15-Jan-1999
Note: Given the relative closeness of the new millenium and the ever increasing
length of the human lifespan, it is advised to output dates with a four digit
year to avoid ambiguity.
Converting a String to a Date
To convert a string into a Date object the scand method of the Util Object, is used. It accepts a
format string that it uses as a hint as to the order of the year, month, and day in the input
string.
/* Example of util.scand */
/* Create some strings containing the same date in differing formats. */
var s1 = "03/12/97";
var s2 = "80/06/01";
var s3 = "December 6, 1948";
var s4 = "Saturday 04/11/76";
var s5 = "Tue. 02/01/30";
var s6 = "Friday, Jan. the 15th, 1999";
/* Convert the strings into Date objects using util.scand */
var d1 = util.scand("mm/dd/yy", s1);
var d2 = util.scand("yy/mm/dd", s2);
var d3 = util.scand("mmmm dd, yyyy", s3);
var d4 = util.scand("mm/dd/yy", s4);
var d5 = util.scand("yy/mm/dd", s5);
var d6 = util.scand("mmmm dd, yyyy", s6);
/* Print the dates to the console using util.printd */
console.println(util.printd("mm/dd/yyyy", d1));
console.println(util.printd("mm/dd/yyyy", d2));
console.println(util.printd("mm/dd/yyyy", d3));
Acrobat Forms - JavaScript Object Specification 59
console.println(util.printd("mm/dd/yyyy", d4));
console.println(util.printd("mm/dd/yyyy", d5));
console.println(util.printd("mm/dd/yyyy", d6));
The output of this script would look like:
03/12/1997
06/01/1980
12/06/1948
04/11/1976
01/30/2002
01/15/1999
Unlike the date constructor (new Date(...)), scand is rather forgiving in terms of the string
passed to it.
Note: Given a two digit year for input, scand resolves the ambiguity as follows: if
the year is less than 50 then it is assumed to be in the 21st century (i.e. add
2000), if it is greater than or equal to 50 then it is in the 20th century (add
1900). This heuristic is often known as the Date Horizon.
Date Arithmetic
It is often useful to do arithmetic on dates to determine things like the time interval between
two dates or what the date will be several days or weeks in the future. The JavaScript Date
object provides several ways to do this. The simplest and possibly most easily understood
method is by manipulating dates in terms of their numeric representation. Internally, JavaScript
dates are stored as the number of milliseconds (one thousand milliseconds is one whole
second) since a fixed date and time. This number can be retrieved through the valueOf method
of the Date object. The Date constructor allows the construction of a new date from this
number.
/* Example of date arithmetic. */
/* Create a Date object with a definite date. */
var d1 = util.scand("mm/dd/yy", "4/11/76");
/* Create a date object containing the current date. */
var d2 = new Date();
/* Number of seconds difference. */
var diff = (d2.valueOf() - d1.valueOf()) / 1000;
/* Print some interesting stuff to the console. */
console.println("It has been " + diff + " seconds since 4/11/1976");
console.println("It has been " + diff / 60 + " minutes since 4/11/1976");
console.println("It has been " + (diff / 60) / 60 + " hours since 4/11/1976");
console.println("It has been " +
Acrobat Forms - JavaScript Object Specification 60
Previous Next