Using JavaScript in Forms¶
In this chapter you will learn how to extend the functionality of Acrobat forms through the application of JavaScript. You will learn how to generate, modify, and enhance all types of PDF forms and the elements they contain, and ensure the proper collection and export of information in various formats relevant to your workflow needs. In addition, you will understand how to leverage the XML Forms Architecture (XFA) so that your presentation format will be not only responsive to user input, but will also ensure that the information can be exchanged with web services and enterprise infrastructures.
Forms essentials¶
You can extend the capability of your forms by using JavaScript to automate formatting, calculations, and data validation. In addition, you can develop customized actions assigned to user events. Finally, it is possible for your forms to interact with databases and web services.
About PDF forms¶
There are two types of PDF forms: Acrobat forms and Adobe LiveCycle Designer forms (XML form object model).
Acrobat forms present information using form fields. They are useful for providing the user with a structured format within which to view or print information. Forms permit the user to fill in information, select choices, and digitally sign the document. Once the user has entered data, the information within the PDF form can be sent to the next step in the workflow for extraction or, in the case of browser-based forms, immediately transferred to a database.
The XML form object model uses a document object model (DOM) architecture to manage the components that comprise a form. These include the base template, the form itself, and the data contained within the form fields. In addition, all calculations, validations, and formatting are specified and managed within the DOM and XML processes.
A static XML form presents a fixed set of text, graphics, and field areas at all times. Dynamic XML forms are created by dividing a form into a series of subforms and repeating subforms. They support dynamically changing fields that can grow or shrink based on content, variable-size rows and tables, and intelligent data import/export features.
Elements of Acrobat forms¶
The form fields used in Acrobat forms are the basis of interaction with the user. They include buttons, check boxes, combo boxes, list boxes, radio buttons, text fields, and digital signature fields. In addition, you can enhance the appearance and value of your forms through the use of tables, templates, watermarks, and other user interface elements such as bookmarks, thumbnails, and dialog boxes. Finally, the JavaScript methods you define in response to events will help customize the utility and behavior of the form within the context of its workflow.
Text fields can be useful for either presenting information or collecting data entered by the user, such as an address or telephone number.
Digital signature fields can be used to ensure the security of a document.
When presenting the user with decisions or choices, you can use check boxes and radio buttons for a relatively small set of choices, or list boxes and combo boxes for a larger set of dynamically changing choices.
Guidelines for creating a new form¶
When designing a PDF form, consider first its purpose and the data it must manage. It may be that the same page is used in multiple contexts, depending on user interactions and decisions. In this case, there may be multiple sets of form fields. When this occurs, treat each set of form fields as a different problem, as though each set had its own page. This will also require extra logic applied to visibility settings. Your form design may have dynamically changing features such as the current date, as well as convenience options such as automatic generation of email messages. It may even have a dynamically changing appearance and layout which is responsive to user interactions.
Usability is a major factor in the design of forms since they are essentially graphical user interfaces, so layout and clarity will be a major consideration. Finally, consider the medium in which the form will be presented: screens with limited resolution may affect your decisions, and printing characteristics may also be relevant.
When creating forms programmatically, consider the form elements that will be needed for a given area. Declare those variables associated with the form elements, and apply logical groupings to those elements that belong to the same collections, such as radio buttons or check boxes. This will simplify the task of assigning properties, formatting options, validation scripts, calculation scripts, and tabbing order to each of the individual form elements.
The creation of a new form, whether done through the Acrobat layout tools or programmatically through JavaScript, will require that you consider the following:
- How the form fields will be positioned.
- Which form fields will be associated in collections so that their properties can be set with consistency and efficiency.
- How size, alignment, and distribution of form fields within the document will be determined.
- When and how to set up duplicate form fields so that when the user types information into one form field, that information automatically appears in the duplicate form fields.
- When to create multiple form fields for array-based access and algorithms.
- The tab order of form fields.
Creating Acrobat form fields¶
There are seven types of Acrobat form fields, each associated with a field type value as shown in the following table.
Add debug JavaScript
The JavaScript debugger in Acrobat lets you review your code line by line, set breakpoints, and inspect variables using the debugger dialog.
To enable JavaScript Debugger, go to Edit > Preferences > JavaScript, and then select the Enable JavaScript debugger after Acrobat is restarted option.
To start the debugger, choose Tools > JavaScript > Debugger.
Manage Document JavaScript
You can use the Document JavaScript dialog box to add, edit, or delete scripts in your current document.
To open the dialog box, choose Tools > JavaScript > Document JavaScript.
JavaScript Editor
You can use the JavaScript Editor to create and edit scripts.
To open the editor, choose Tools > JavaScript > All JavaScripts.
Document actions and JavaScript
You can associate a particular JavaScript to a specific document action. When the action is triggered, the script executes.
To open the Document Actions dialog, choose Tools > JavaScript > Document Actions.
Select an action and then click Edit to add the script to the action.
Customize PDFs using JavaScript
One of the easiest and most powerful ways to customize PDF files is by using JavaScript. Based on JavaScript version 1.5 of ISO-16262 (formerly known as ECMAScript), JavaScript in Adobe Acrobat software implements objects, methods, and properties that enable you to manipulate PDF files, produce database-driven PDF files, modify the appearance of PDF files, and much more. You can tie Acrobat JavaScript code to a specific PDF document, a page, field, or button within that document, or a field or button within the PDF file, and even to a user action.
JavaScript is useful for XML forms. JavaScript enables automated forms handling, Web and database communication, commenting, and user-interface capabilities. PDF files created with Acrobat and Adobe LiveCycle tools allow data to be extracted as XML into custom schemas. Applications written in Java and other languages easily integrate Acrobat with web services using Simple Object Access Protocol (SOAP).