bc Adobe® Acrobat® Technical Note # 5186 Acrobat Forms JavaScript Object Specification Version 4.
© 1999 Adobe Systems Incorporated. All rights reserved. The information in this document is furnished for informational use only, is subject t change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.
Table Of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Other useful documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 What’s New for 4.0 . . . . . . . . . . . . . . . . . . . . . . .
Doc Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Doc Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Doc Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keystroke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Field Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 buttonImportIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 clearItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaScript Object Specification Introduction JavaScript, the scripting language developed by Netscape Communications, enables you to easily create interactive Web pages. JavaScript v1.2 comes with six predefined classes: Boolean, Number, Date, Math, String, and Array. As part of the integration with Adobe® Acrobat® Forms, we have defined additional classes and objects to allow access to portions of the PDF file.
with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http:// beta1.adobe.com/ada/acrosdk/DOCS/VWRPIREF.PDF. Document Conventions As this document pertains to Acrobat Forms version 3.5 and greater, there exists some compatibility issues with older versions of the software. If a property, method, or object is marked with a #.# symbol, then it is available only in versions of the Acrobat Forms software greater than or equal to #.#.
What’s New for 4.
Acrobat Forms JavaScript Object Model Acrobat Forms defines an object model on top of JavaScript 1.2. These objects are only defined within the Adobe Acrobat realm and are specific to Acrobat Forms. They basically mirror the Acrobat Forms components and give the forms developer a way to access these components programmatically in order to query and change their properties.
This property puts the Acrobat viewer in fullscreen mode vs. regular viewing mode. Example: // on mouse up, set to fullscreen mode app.fullscreen = true; In the above example, the Adobe Acrobat viewer is set to fullscreen mode when app.fullscreen is set to true. If app.fullscreen was false then default viewing mode would be set. The default viewing mode is defined as the original mode the Acrobat application was in before full screen mode was initiated.
platform Type: String Access: R This property returns the platform that the script is currently executing on. Valid values include “WIN”, “MAC”, and “UNIX”. toolbar Type: Boolean Access: R/W This property allows a script to show or hide both the horizontal and vertical Acrobat tool bars. It does not hide the tool bar in external windows (i.e. in an Acrobat window within a Web browser). Example: // Opened the document, now remove the toolbar. app.toolbar = false; toolbarHorizontal Type: Boolean 4.
App Object Methods alert Parameters: cMessage, [nIcon], [nType] Returns: nButton This method displays an alert dialog on the screen. The minimum required parameter is a string containing the message to be displayed. Optionally, an icon type can be specified by using the nIcon parameter.
This method causes the system to play a sound. The various sounds and the values used are as follows: Message Type Value Error (default) 0 Warning 1 Question 2 Status 3 Default 4 On Apple Macintosh and UNIX systems the beep type is ignored. execMenuItem 4.0 Parameters: cMenuItem Returns: nothing This method executes the specified menu item. To find out the exact menu item name, see the Acrobat Viewer Plug-in API On-line Reference under § Lists: Menu item names.
goBack Parameters: None Returns: nothing Use this function to go to the previous view on the view stack. This is equivalent to pressing the go back button on the Acrobat tool bar. goForward Parameters: None Returns: nothing Use this function to go to the next view on the view stack. This is equivalent to pressing the go forward button on the Acrobat tool bar. hideMenuItem 4.0 Parameters: cName Returns: nothing This method only works in the Config.js Plug-in folder level script.
If bUI is set to false, the cTo parameter is required and others are optional. You must use a semicolon “;” to separate multiple recipients in cTo, cCc, cBcc parameters. The length limit for cSubject and cMsgBody is 64k bytes. Example: /* This will pop up the compose new message window */ app.mailMsg(true); /* This will send out the mail to fun1@fun.com and fun2@fun.com */ app.mailMsg(false, "fun1@fun.com; fun2@fun.com ", "", "", "This is the subject", "This is the body of the mail.
Color Arrays A color is represented in JavaScript as an array containing 1, 2, 4, or 5 elements corresponding to a transparent, gray, RGB, or CMYK color space, respectively. The first element in the array is a string denoting the color space type. The subsequent elements are numbers that range between zero and one inclusive.
Color Properties The color object defines the following colors and there associated keywords: Color Object Keyword Version Transparent color.transparent Black color.black White color.white Red color.red Green color.green Blue color.blue Cyan color.cyan Magenta color.magenta Yellow color.yellow Dark Gray color.dkGray 4.0 Gray color.gray 4.0 Light Gray color.ltGray 4.
Console Object The Console object is a static object to access the JavaScript console for displaying debug messages. It functions only within Acrobat Exchange. Console Methods show Parameters: none Returns: none This method shows the console window. hide Parameters: none Returns: none This method closes the console window. println Parameters: cMessage Returns: none This method prints the string value of cMessage to the console window with an accompanying carriage return.
Doc Object The JavaScript Doc object provides the interfaces between a PDF document open in the viewer and the JavaScript interpreter. It provides methods and properties of the PDF document. Doc Access from JavaScript Accessing the Doc object from JavaScript can be done either through the this Object, which usually points to the Doc object of the underlying document. The target event property points to the field that initiated the event for all mouse, calculate, validate, and format events.
creationDate Type: Date Access: R This property defines the documents creation date. delay 4.0 Type: Boolean Access: R/W This property delays the redrawing of any appearance changes to every field in the document. It is generally used to buffer a series of changes to fields before requesting that the fields regenerate their appearance. Setting the property to true forces all changes to be queued until delay is reset to false. Once set to false then all the fields on the page are re-drawn.
keywords Type: String Access: R/W This property specifies the document’s keywords in the Adobe Acrobat File->Document Info>General dialog box. modDate Type: Date Access: R This property contains the date the document was last modified. numFields Type: Integer 4.0 Access: R This property returns the total number of fields in the document. See also the getNthFieldName method. numPages Type: Integer Access: R This property contains the number of pages in the document.
Use this property to get or set a page of the document. When setting the pageNum to a specific page, remember that the values are “0” based. // This example will go to the first page of the document. this.pageNum = 0 ; Or pageNum can be used to advance “n” pages in the document: // This example will advance the document to the next page this.pageNum++; producer Type: String Access: R This property contains producer of the document (e.g. “Acrobat Distiller”, “PDFWriter”, etc.).
zoomType Type: String Access: R/W This property specifies the current zoom type of the document. Valid zoom types are: none, fit page, fit width, fit height, and fit visible width. A convenience zoomType object that defines all the valid zoom types is provided for use from JavaScript. It provides the following zoom types: Zoom Type Keyword NoVary zoomtype.none FitPage zoomtype.fitP FitWidth zoomtype.fitW FitHeight zoomtype.fitH FitVisibleWidth zoomtype.fitV Preferred zoomtype.
The optional aFields parameter is the array of field names to submit or a string containing a single field name. If this parameter is present then only the fields indicated are exported, except those excluded by parameter bEmpty or bNoPassword. If this parameter is omitted or is null then all fields in the form are exported (again subject to the restrictions of bEmpty).
getNthTemplate Parameters: nWhich Returns: cName Use this function to retrieve the name of a template within in the document. (See also the numTemplates property and spawnPageFromTemplate method.) getURL 4.0 Parameters: cURL, [bAppend] Returns: nothing This method retrieves the specified URL over the internet using a GET. If the current document is being viewed inside the browser or Acrobat Web Capture is not available, it uses the Weblink plug-in to retrieve the requested URL.
of the parameters are used to seed the compose new message window that is displayed to the user. If bUI is set to false, the cTo parameter is required and all others are optional. You must use a semicolon “;” to separate multiple recipients in cTo, cCc, cBcc parameters. The length limit for cSubject and cMsgBody is 64k bytes. Example: /* This will pop up the compose new message window */ this.mailDoc(true); /* This will send out the mail with the attached PDF file to fun1@fun.com and fun2@fun.com */ this.
Note: This is a Windows-only feature. In addition, the client machine must have its default mail program configured to be MAPI enabled in order to use this method. print Parameters: bInteractive, [nFirstPage], [nLastPage], [bSilent] Returns: nothing Use this function to print all or a specific number of pages of the document. If bInteractive is true, Acrobat displays the standard print dialog and all other parameters are ignored.
Use this function to scroll the current page to the location specified by xOrigin and yOrigin. These coordinates must be defined in user space. Please refer to the PDF Reference Manual Version 1.3 for more details on the user space coordinate system. spawnPageFromTemplate Parameters: cTemplate, [nPage], [bRename], [bInsert] Returns: nothing Use this method with a template name, such as the ones returned by getNthTemplate.
The optional aFields parameter is the array of field names to submit or a string containing a single field name. If this parameter is present then only the fields indicated are submitted, except those excluded by parameter bEmpty. If this parameter is omitted or is null then all fields in the Form are submitted (again subject to the restrictions of bEmpty). You can include non-terminal fields in the array or the string passed as a parameter: this is a simple shortcut for having a whole subtree submitted.
Event Object All JavaScripts are executed as the result of a particular event (also referred to as a trigger). Acrobat Forms accepts the following events and executes any scripts that are specified for these events: mouse enter, mouse down, mouse up, mouse exit, keystroke, format, validate, and calculate. It is important to JavaScript writers to know what these events are and when and what order they are processed.
The user interface for Acrobat Forms allows the author to specify a Selection Change script for list boxes. The script is triggered every time an item is selected. This is implemented as the keystroke event where the keystroke value is equivalent to the user selection . This behavior is also implemented for the combo box —the “keystroke” could be thought to be a paste into the text field of the value selected from the drop down list.
Event Object Properties change Type: String Event: Keystroke, Selection ChangeAccess: R/W This property specifies the change in value that the user has just typed. The change is replaceable such that if the JavaScript wishes to substitute certain characters, it may. commitKey Type: Number 4.0 Event: Keystroke, Format Access: R Use this property to determine how a form field lost focus. Valid values are: 0 - value was not committed (e.g. escape key was pressed).
For each event, except the mouse related events, the static event object is populated with the following data. In most events, it is important for JavaScript to set the rc (return code) property to indicate that the event can proceed. selEnd Type: Integer Event: Keystroke Access: R/W This property specifies the ending position of the current text selection during a keystroke event.
app.alert("Invalid value for field " + event.target.name); event.rc = false; } For a calculate event, JavaScript should set this property. This is the value that the field should take upon completion of the event. For example, the following JavaScript sets the calculated value of the field to the value of the SubTotal field plus tax. var f = this.getField("SubTotal"); event.value = f.value * 1.0725; For a format event, JavaScript should set this property.
Field Object The Field object represents an Acrobat form field (that is, a field created using the Acrobat form tool). In the same manner that an author might want to modify an existing field’s properties like the border color or font, the Field object gives the JavaScript user the ability to perform the same modifications. Field Access from JavaScript Before a field can be accessed, it must be “bound” to a JavaScript variable through a method provided by the this Object methods interface.
Field Property Name Type Text Field Combo Box List Box Push Button Check Box Radio Button Signa ture Read Access Write Access ✓ ✓ ✓ ✓ highlight String lineWidth Integer ✓ lineWidth Boolean ✓ name String ✓ numItems Integer password Boolean ✓ print Boolean ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ readonly Boolean ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ required Boolean ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ strokeColor Array ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ style String ✓ ✓ ✓ ✓ textColor Array ✓ ✓ ✓ ✓ ✓ ✓ ✓
borderStyle Type: String Fields: All Access: R/W This property specifies the border style for a field. Valid border styles include solid, dashed, beveled, inset, and underline. The border style determines how the border for the rectangle is drawn. • The solid style strokes the entire perimeter of the rectangle with a solid line. • The dashed style strokes the perimeter with a dashed line.
var a = this.getField("newItem"); var b = this.getField("oldItem"); a.calcOrderIndex = b.calcOrderIndex + 1; In this example, the this Object method getField, gets the newItem field that was added after ‘oldItem’ field. It then changes the calcOrderIndex of the oldItem field so that it is calculated before ‘newItem’ field. charLimit Type: Integer Fields: Text Access: R/W This property limits the number of characters that a user can type into a text field.
display 4.0 Type: Integer Fields: All Access: R/W This property controls whether the field is hidden or visible on screen and in print: Effect Keyword Field is visible on screen and in print display.visible Field is hidden on screen and in print display.hidden Field is visible on screen but doesn’t print display.noPrint Field is hidden on screen but prints display.noView This property supersedes the older hidden and print properties.
f.fillColor = color.blue; else f.fillColor = color.yellow; In older versions of this specification, this property was named bgColor. The use of bgColor is now discouraged but for backwards compatibility is still valid. hidden Type: Boolean Fields: All Access: R/W This property controls whether the field is hidden or visible to the user. If the value is false the field is visible, true the field is invisible. The default value for hidden is false. // Set the field to hidden var f = this.
The following example sets the highlight property of a button to “invert”. // set the highlight mode on button to invert var f = this.getField("MyButton"); f.highlight = highlight.i; lineWidth Type: Integer Fields: All Access: R/W This property specifies the thickness of the border when stroking the perimeter of a field’s rectangle. If the stroke color is transparent, this parameter has no effect except in the case of a beveled border.
This property allows you to access the fully qualified field name of the field as a string object. var f = this.getField("MyField"); console.println(f.name); numItems Type: Integer Fields: Combo & Listbox Access: R The number of items in the combo or list box. password Type: Boolean Fields: Text Access: R This property causes the field to display asterisks for the data entered into the field. Upon submission, the actual data entered is sent.
This property sets or gets the required characteristic of a field. If a field is required its value must be non-null when the user clicks a submit button that causes the value of the field to be posted. If the field value is null, the user receives a warning message and the submit does not occur. var f = this.getField("MyField"); f.
textColor Type: Array Fields: All Access: R/W This property determines the foreground color of a field. It represents the text color for text, button, or list box fields and the check color for check box or radio button fields. Values are defined the same as the fillColor property. Refer to the Color Arrays section for information on defining color arrays and how values are set and used with this property. var f = this.getField("MyField"); f.textColor = color.
The following example illustrates the use of this property and the font object. // set the font of MyField to Helvetica var f = this.getField("MyField"); f.textFont = font.Helv; textSize Type: Integer Fields: All Access: R/W This property determines the text size in points that is used in all controls. In combo box and radio button fields, the text size determines the size of the check. Valid text sizes include zero and the range from 4 to 144 inclusive.
var filter = this.getField("Filter"); event.value = (oil.value + filter.value) * 1.0725; In this example, the value of the field being calculated is set to the sum of the oil and filter fields and multiplied by the state sales tax. Value is perhaps the most important of all the field properties. Field Methods buttonImportIcon Parameter: none Returns: nothing This method imports the appearance of a button from another PDF file. It prompts the user to select a PDF file available on the system.
This function returns an array of terminal children fields (i.e. fields that can have a value) for a parent field. This method can be particularly useful for doing field calculations in tables where a parent field value is the sum of all of its children. To understand more about field name and hierarchies, please see the section on Field Properties. // f has 3 children: f.v1, f.v2, f.v3 var f = this.getField("f"); var a = f.getArray(); var v = 0.0; for (j =0; j < a.length; j++) v += a[j].
Returns: nothing This method sets the list of items for a combo box or a list box. The single parameter necessary to call this method must be an array. Each element in the array must either be an object convertible to a string or another array. If the element can be converted to a string, the user and export values for the list item are equal to the string. If the element is an array it must consist of two sub-elements.
Global Object The Global object is a static JavaScript object that allows you to share data between documents and have data be persistent across sessions. This is referred to as persistent global data. Global data-sharing and notification across documents is done through a publish and subscribe mechanism. This mechanism gives you the ability to monitor global data variables and report their value changes across documents. Global data can be specified by adding properties to the global object.
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.
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.
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.
printd Parameters: cFormat, date Returns: cResult Use this method to format a date according to a format string.
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.
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.
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.
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.
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.
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.
((diff / 60) / 60) / 24 + " days since 4/11/1976"); console.println("It has been " + (((diff / 60) / 60) / 24) / 365 + " years since 4/11/1976"); The output of this script would look something like: It It It It It has has has has has been been been been been 718329600 seconds since 4/11/1976 11972160 minutes since 4/11/1976 199536 hours since 4/11/1976 8314 days since 4/11/1976 22.7780821917808 years since 4/11/1976 The following example shows the addition of dates. /* Example of date arithmetic.
infrastructure to lock a form for a particular set of people or allowing a form to expire after a certain time period. The ability to set a user password is accessed using the Save As function by choosing the appropriate security handler and configuring its settings.
“official”. A blind signature (signed without any appearance) is often useful in this situation and can be created via the pull right menu in the signatures pane. After fill-in a user can also sign the document either by using the signing tool or filling in a pre-authored signature field, thus ensuring that the form undergoes no further changes without detection. Working with Signature Fields 4.0 Signature fields allow the user to digitally sign a document.
AFSignatureLock(this, "THESE", "B", !bLock); See the comments in AForm.js for more details.
