Related Manuals for Adobe ACROBAT FORMS JAVASCRIPT OBJECT
Summary of Contents for Adobe ACROBAT FORMS JAVASCRIPT OBJECT
- Page 1 Adobe Acrobat ® ® Technical Note # 5186 Acrobat Forms JavaScript Object Specification Version 4.0 Revised: January 27, 1999...
- Page 2 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 inaccura- cies that may appear in this document.
-
Page 3: Table Of Contents
Table Of Contents Introduction ............... . 7 Other useful documents . - Page 4 Doc Object ............... . . 20 Doc Access from JavaScript .
- Page 5 Keystroke ..............31 Validate .
- Page 6 value ..............46 Field Methods .
-
Page 7: Introduction
Acrobat Form fields including their formatting, calculation, and validation. The intended audience of this document is assumed to be familiar with Adobe Acrobat, the Acrobat Forms plug-in and the Adobe Acrobat plug-in API. Other useful documents For more information on JavaScript, please see Netscape’s JavaScript Reference Manual... -
Page 8: Document Conventions
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... -
Page 9: What's New For 4.0
What’s New for 4.0 Object Properties Methods App Object formsVersion, getNthPlugInName(), numPlugIns, hideMenuItem(), openInPlace, hideToolbarButton(), mailMsg() toolbarHorizontal, toolbarVertical, viewerVersion Color Object dkGray, gray, ltGray Doc Object calculate, delay, exportAsFDF(), external, numFields getNthFieldName(), getURL(), importAnFDF(), mailDoc(), mailForm(), spawnPageFromTemplate(), submitForm() Field Object display setItems(), deleteItemAt() Util Object... -
Page 10: 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. -
Page 11: Language
// 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. -
Page 12: Platform
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. -
Page 13: App Object Methods
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. -
Page 14: Execmenuitem
This method causes the system to play a sound. The various sounds and the values used are as follows: Message Type Value Error (default) Warning Question Status Default On Apple Macintosh and UNIX systems the beep type is ignored. execMenuItem Parameters: cMenuItem Returns: nothing This method executes the specified menu item. -
Page 15: Goback
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. -
Page 16: Response
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);... -
Page 17: Color Arrays
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. -
Page 18: Color Properties
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 color.red Green color.green Blue color.blue Cyan color.cyan Magenta color.magenta Yellow color.yellow Dark Gray color.dkGray Gray color.gray Light Gray color.ltGray Example: // This example sets the text color of the field to red... -
Page 19: Console Object
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. -
Page 20: Doc Object
This property supersedes the application level property whose use is now discouraged. creator Type: String Access: R This property defines the creator of the document (e.g. “Adobe FrameMaker”, “Adobe PageMaker”, etc.). Acrobat Forms - JavaScript Object Specification... -
Page 21: Creationdate
creationDate Type: Date Access: R This property defines the documents creation date. delay 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. -
Page 22: 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 Access: R This property returns the total number of fields in the document. -
Page 23: Producer
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”... -
Page 24: Zoomtype
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... -
Page 25: Getfield
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). -
Page 26: Getnthtemplate
getNthTemplate Parameters: nWhich Returns: cName Use this function to retrieve the name of a template within in the document. (See also the numTemplates spawnPageFromTemplate property and method.) getURL 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. -
Page 27: Mailform
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. -
Page 28: Print
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. -
Page 29: Spawnpagefromtemplate
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... - Page 30 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).
-
Page 31: Event Object
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. -
Page 32: Validate
To change the calculation order of fields, use the Tools->Forms->JavaScript->Set Calculation Order... menu item in Adobe Acrobat. Format Once all dependent calculations have been performed the format event is triggered. This event allows the attached JavaScript to change the way that the data value appears to a user (also known as its presentation or appearance). -
Page 33: Event Object Properties
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 Event: Keystroke, Format... -
Page 34: Selend
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... -
Page 35: Willcommit
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. -
Page 36: Field Object
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. -
Page 37: Alignment
Field Property Type Text Combo List Push Check Radio Signa Read Write Name Field Button Button ture Access Access String highlight Integer lineWidth Boolean lineWidth String name Integer numItems Boolean password Boolean print Boolean readonly Boolean required Array strokeColor String style Array textColor... -
Page 38: Borderstyle
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. •... -
Page 39: Charlimit
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’... -
Page 40: Display
display 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... -
Page 41: Hidden
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. -
Page 42: Linewidth
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. -
Page 43: Numitems
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... -
Page 44: Strokecolor
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. -
Page 45: Textcolor
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 fillColor Color Arrays defined the same as the... -
Page 46: Textsize
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. -
Page 47: Field Methods
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. -
Page 48: Getitemat
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 Field Properties. - Page 49 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.
-
Page 50: Global Object
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. - Page 51 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 Plug-in folder level application exit and re-loaded at application start. See the section on scripts for more details.
-
Page 52: This Object
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. Plug-in folder level •... -
Page 53: Util Object
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. -
Page 54: Printd
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 Abbreviated month Sept Numeric month with leading zero Numeric month without leading zero dddd Long day... -
Page 55: Scand
scand 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. -
Page 56: Implementation Considerations
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. -
Page 57: Field Level
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. -
Page 58: Working With The Date Object
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");... -
Page 59: Converting A String To A Date
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: "... -
Page 60: Date Arithmetic
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 scand Unlike the date constructor (new Date(...)), is rather forgiving in terms of the string passed to it. scand Note: Given a two digit year for input, resolves the ambiguity as follows: if the year is less than 50 then it is assumed to be in the 21st century (i.e. -
Page 61: Acrobat Forms And Security
((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 has been 718329600 seconds since 4/11/1976 It has been 11972160 minutes since 4/11/1976 It has been 199536 hours since 4/11/1976... -
Page 62: Restricting Permissions
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. Restricting Permissions The standard security model in Acrobat is accessible at document save time and allows you to set the following restrictions on the document: printing, changing the document, selecting text... -
Page 63: Working With Signature Fields
“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. - Page 64 AFSignatureLock(this, "THESE", "B", !bLock); See the comments in AForm.js for more details. Acrobat Forms - JavaScript Object Specification...