Developing Acrobat Applications Using JavaScript

217 Pages·2015·2.78 MB·English

by  Adobe Developer Support

bbc
Developing Acrobat Applications
®
Using JavaScript™
Adobe Acrobat DC SDK
® ®
May 2015
© 2015 Adobe Systems Incorporated. All rights reserved.
Adobe® Acrobat® DC SDK Developing Acrobat Applications Using JavaScript for Microsoft® Windows® and Mac OS®
Edition 1.0, May 2015
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished
under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part
of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording,
or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected
under copyright law even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to 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 the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The
unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to
obtain any permission required from the copyright owner.
Any references to company names and company logos in sample material are for demonstration purposes only and are not intended to refer
to any actual organization.
Adobe, the Adobe logo, Acrobat, After Effects, FrameMaker, Illustrator, LiveCycle, Photoshop, PostScript and Reader are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries.
JavaScript is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
All other trademarks are the property of their respective owners.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101,
consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R.
§12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable,
the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users
(a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA
95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if
appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of
1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60,
60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents
List of Examples.........................................................................................................................10
1 Preface........................................................................................................................................12
What’s in this guide?...................................................................................................................................................................12
Who should read this guide?...................................................................................................................................................12
About the sample scripts...........................................................................................................................................................12
Related documentation.............................................................................................................................................................13
1 Introduction...............................................................................................................................14
Overview..........................................................................................................................................................................................14
Reading the JavaScript for Acrobat API Reference..............................................................................................................15
Object summary...........................................................................................................................................................................16
app...............................................................................................................................................................................................16
Doc..............................................................................................................................................................................................17
dbg..............................................................................................................................................................................................17
console.......................................................................................................................................................................................17
global..........................................................................................................................................................................................17
util................................................................................................................................................................................................18
dialog..........................................................................................................................................................................................18
security.......................................................................................................................................................................................18
SOAP...........................................................................................................................................................................................18
search.........................................................................................................................................................................................18
event...........................................................................................................................................................................................19
JavaScript applications...............................................................................................................................................................19
1 Tools ...........................................................................................................................................21
Using the JavaScript Debugger console..............................................................................................................................21
Opening the console............................................................................................................................................................21
Executing JavaScript.............................................................................................................................................................22
Formatting code.....................................................................................................................................................................22
Enabling JavaScript...............................................................................................................................................................22
Debugging with the JavaScript Console.......................................................................................................................23
Using a JavaScript editor...........................................................................................................................................................24
Specifying the default JavaScript editor..............................................................................................................................25
Using an external editor.............................................................................................................................................................25
Additional editor capabilities............................................................................................................................................26
Specifying additional capabilities to your editor.......................................................................................................26
Saving and closing a file with a syntax error................................................................................................................27
Using the Debugger with Acrobat Reader..........................................................................................................................28
Enabling the JavaScript Debugger........................................................................................................................................29
JavaScript Debugger...................................................................................................................................................................30
Main groups of controls.......................................................................................................................................................30
Debugger View windows....................................................................................................................................................31
Debugger buttons.................................................................................................................................................................31
Debugger Scripts window..................................................................................................................................................33
Call Stack list............................................................................................................................................................................35
Inspect details window........................................................................................................................................................35
3
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 4
Coding styles and breakpoints...................................................................................................................................37
Listing breakpoints.........................................................................................................................................................38
Using conditional breakpoints...................................................................................................................................38
Starting the Debugger.........................................................................................................................................................38
Final notes................................................................................................................................................................................39
1 JavaScript Contexts in Acrobat ................................................................................................40
The concept of a JavaScript event.........................................................................................................................................40
About contexts..............................................................................................................................................................................41
Folder level...............................................................................................................................................................................42
Document level......................................................................................................................................................................43
Page level..................................................................................................................................................................................43
Field level..................................................................................................................................................................................44
Privileged versus non-privileged context...........................................................................................................................45
Executing privileged methods in a non-privileged context...................................................................................45
Executing privileged methods through the menu....................................................................................................46
Executing privileged methods in a certified document..........................................................................................48
1 Creating and Modifying PDF Documents................................................................................49
Creating and modifying PDF files...........................................................................................................................................49
Combining PDF documents...............................................................................................................................................50
Combining and extracting files.........................................................................................................................................51
Creating file attachments....................................................................................................................................................52
Cropping and rotating pages............................................................................................................................................54
Cropping pages................................................................................................................................................................55
Rotating pages..................................................................................................................................................................55
Extracting, moving, deleting, replacing, and copying pages................................................................................56
Adding watermarks and backgrounds...........................................................................................................................58
Converting PDF documents to XML format.......................................................................................................................58
1 Print Production ........................................................................................................................60
Setting print options...................................................................................................................................................................60
Printing PDF documents............................................................................................................................................................62
Silent printing..........................................................................................................................................................................63
Printing comments and forms..........................................................................................................................................63
Booklet printing......................................................................................................................................................................64
Setting advanced print options........................................................................................................................................64
Specifying output settings...........................................................................................................................................65
Specifying marks and bleeds.......................................................................................................................................65
Setting PostScript options............................................................................................................................................65
Setting font options........................................................................................................................................................65
1 Using JavaScript in Forms.........................................................................................................67
Forms essentials............................................................................................................................................................................67
About PDF forms....................................................................................................................................................................67
Elements of Acrobat forms...........................................................................................................................................68
Guidelines for creating a new form...........................................................................................................................68
Creating Acrobat form fields..............................................................................................................................................69
Setting Acrobat form field properties............................................................................................................................70
Field properties................................................................................................................................................................70
Button fields......................................................................................................................................................................72
Check box fields...............................................................................................................................................................74
Combo box fields.............................................................................................................................................................75
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 5
List box fields.....................................................................................................................................................................79
Radio button fields..........................................................................................................................................................80
Signature fields.................................................................................................................................................................81
Text fields............................................................................................................................................................................82
Validation scripts..............................................................................................................................................................83
Calculation script.............................................................................................................................................................84
Task-based topics.........................................................................................................................................................................85
Highlighting required form fields....................................................................................................................................85
Making a form fillable...........................................................................................................................................................86
Setting the hierarchy of form fields.................................................................................................................................86
Creating forms........................................................................................................................................................................88
Positioning form fields...................................................................................................................................................88
Duplicating form fields..................................................................................................................................................88
Creating multiple form fields......................................................................................................................................89
Defining the tabbing order................................................................................................................................................90
Defining form field calculation order.............................................................................................................................90
Making PDF forms web-ready...........................................................................................................................................90
Creating a submit button.............................................................................................................................................91
Creating a reset form button.......................................................................................................................................91
Defining CGI export values..........................................................................................................................................91
Importing and exporting form data................................................................................................................................91
Emailing completed forms.................................................................................................................................................92
Use date objects.....................................................................................................................................................................92
Date arithmetic.......................................................................................................................................................................94
Defining global variables in JavaScript..........................................................................................................................95
Enable the global object security policy.................................................................................................................95
Setting and getting a global variable.......................................................................................................................95
Deleting global variables..............................................................................................................................................96
Making global variables persistent...........................................................................................................................96
Querying an Acrobat form field value in another open form..........................................................................96
Global object security policy.......................................................................................................................................97
Intercepting keystrokes in an Acrobat form.................................................................................................................97
Constructing custom colors...............................................................................................................................................98
Prompting the user for a response..................................................................................................................................98
Fetching an URL from JavaScript.....................................................................................................................................98
Creating special rollover effects.......................................................................................................................................98
Introduction to XML forms architecture (XFA)..................................................................................................................98
Enabling dynamic layout and rendering.......................................................................................................................99
Growable form fields............................................................................................................................................................99
Variable-size rows and tables............................................................................................................................................99
Multiple customized forms within a form based on user input............................................................................99
Handling image data............................................................................................................................................................99
Dynamic tooltips....................................................................................................................................................................99
XFA-specific JavaScript methods..................................................................................................................................100
JavaScript methods not enabled in XML Forms......................................................................................................103
ADO support for Windows..............................................................................................................................................104
Detecting XML forms and earlier form types............................................................................................................104
Saving form data as XML or XML Data Package (XDP)..........................................................................................104
Global submit.......................................................................................................................................................................104
Making forms accessible.........................................................................................................................................................105
Text-to-speech.....................................................................................................................................................................106
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 6
Tagging annotations.........................................................................................................................................................107
Document metadata..........................................................................................................................................................107
Short description.................................................................................................................................................................108
Setting tab order.................................................................................................................................................................108
Reading order.......................................................................................................................................................................108
Using JavaScript to secure forms.........................................................................................................................................108
1 Review, Markup, and Approval..............................................................................................111
Working with comments using JavaScript.......................................................................................................................111
Annotation types................................................................................................................................................................111
Getting annotation data...................................................................................................................................................112
Adding comments with JavaScript...............................................................................................................................113
Setting comment properties..........................................................................................................................................114
Online collaboration essentials............................................................................................................................................114
Reviewing documents with additional usage rights.............................................................................................114
Emailing PDF documents.................................................................................................................................................115
Spell-checking in comments and forms.....................................................................................................................116
Setting spelling preferences.....................................................................................................................................116
Adding words to a dictionary...................................................................................................................................116
Approval.................................................................................................................................................................................116
Managing comments...............................................................................................................................................................116
Selecting, moving, and deleting comments.............................................................................................................117
Using the comments list...................................................................................................................................................117
Changing the status of comments.........................................................................................................................117
Changing the appearance of comments.............................................................................................................117
Sorting comments..............................................................................................................................................................118
Showing and hiding comments..............................................................................................................................118
Exporting and importing comments...........................................................................................................................118
Aggregating comments for use in Excel....................................................................................................................118
Comparing comments in two PDF documents.......................................................................................................119
Extracting comments in a batch process...................................................................................................................119
Approving documents using stamps (Japanese workflows)....................................................................................119
Setting up a Hanko approval workflow......................................................................................................................119
Participating in a Hanko approval workflow.............................................................................................................120
Installing and customizing Hanko stamps..........................................................................................................120
Creating custom Inkan stamps................................................................................................................................120
Deleting custom stamps............................................................................................................................................120
1 Working with Digital Media in PDF Documents....................................................................121
Media players: control, settings, renditions, and events.............................................................................................121
Accessing a list of active players....................................................................................................................................122
Specifying playback settings..........................................................................................................................................122
Monitors........................................................................................................................................................................................124
Integrating media into documents....................................................................................................................................125
Controlling multimedia through a rendition action..............................................................................................127
Controlling multimedia with a Run a JavaScript action........................................................................................128
Adding and editing renditions.......................................................................................................................................130
Setting multimedia preferences..........................................................................................................................................131
1 Modifying the User Interface..................................................................................................132
Adding toolbar buttons and menu items........................................................................................................................132
Adding navigation to PDF documents..............................................................................................................................134
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 7
Thumbnails............................................................................................................................................................................134
Creating page thumbnails.........................................................................................................................................134
Adding page actions with page thumbnails......................................................................................................135
Bookmarks.............................................................................................................................................................................135
Creating bookmarks....................................................................................................................................................136
Managing bookmarks.................................................................................................................................................137
Creating a bookmark hierarchy...............................................................................................................................137
Links.........................................................................................................................................................................................138
Adding and removing web links from text.........................................................................................................139
Adding and removing links.......................................................................................................................................139
Defining the appearance of a link..........................................................................................................................140
Opening links.................................................................................................................................................................140
Opening file attachments..........................................................................................................................................141
Using destinations........................................................................................................................................................141
Using actions for special effects....................................................................................................................................141
Highlighting form fields and navigational components......................................................................................142
Setting up a presentation................................................................................................................................................143
Defining the initial view in full screen view........................................................................................................143
Defining an initial view...............................................................................................................................................144
Numbering pages...............................................................................................................................................................145
Creating buttons.................................................................................................................................................................147
Working with PDF layers.........................................................................................................................................................147
Navigating with layers.......................................................................................................................................................147
Editing the properties of PDF layers.............................................................................................................................148
Reordering layers................................................................................................................................................................149
1 Acrobat Templates..................................................................................................................150
The role of templates in PDF form architecture.............................................................................................................150
Spawning templates................................................................................................................................................................150
Dynamic form field generation......................................................................................................................................151
Dynamic page generation...............................................................................................................................................151
Template syntax and usage............................................................................................................................................151
1 Search and Index Essentials....................................................................................................154
Searching for text in PDF documents................................................................................................................................154
Finding words in an PDF document.............................................................................................................................155
Using advanced search options..............................................................................................................................155
Searching across multiple PDF documents...............................................................................................................156
Searching all PDF files in a specific location.......................................................................................................156
Using advanced search options for multiple document searches.............................................................157
Searching PDF index files...........................................................................................................................................157
Using Boolean queries................................................................................................................................................157
Indexing multiple PDF documents.....................................................................................................................................158
Creating, updating, or rebuilding indexes.................................................................................................................158
Searching metadata.................................................................................................................................................................159
1 Security.....................................................................................................................................160
Security essentials.....................................................................................................................................................................160
Methods for adding security to PDF documents....................................................................................................160
Passwords and restrictions........................................................................................................................................160
Certifying documents.................................................................................................................................................160
Encrypting files using certificates...........................................................................................................................162
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 8
Security policies............................................................................................................................................................163
Secure forms...................................................................................................................................................................163
Digitally signing PDF documents........................................................................................................................................163
Signing a PDF document.................................................................................................................................................163
The security handler object.............................................................................................................................................164
The SignatureInfo object...........................................................................................................................................164
Applying the signature...............................................................................................................................................164
Clearing a digital signature from a signature field...........................................................................................165
Getting signature information from another user..................................................................................................165
Removing signatures.........................................................................................................................................................165
Certifying a document......................................................................................................................................................166
Validating signatures.........................................................................................................................................................166
Setting digital signature properties with seed values...........................................................................................166
Adding security to PDF documents....................................................................................................................................167
Adding passwords and setting security options.....................................................................................................167
Adding usage rights to a document............................................................................................................................167
Encrypting PDF files for a list of recipients................................................................................................................168
Encrypting PDF files using security policies..............................................................................................................170
Adding security to document attachments..............................................................................................................172
Digital IDs and certification methods................................................................................................................................172
Digital IDs...............................................................................................................................................................................172
About digital ID providers.........................................................................................................................................173
Creating a digital ID (default certificate security).............................................................................................174
Using digital IDs (default certificate security).....................................................................................................175
Managing digital IDs (Windows certificate security).......................................................................................176
Managing digital ID certificates.....................................................................................................................................176
Sharing digital ID certificates...................................................................................................................................177
Building a list of trusted identities..........................................................................................................................177
Checking information on certificates....................................................................................................................177
Task based topics......................................................................................................................................................................178
Disallowing changes in scripts.......................................................................................................................................178
Hiding scripts........................................................................................................................................................................178
1 Rights-Enabled PDF Files........................................................................................................179
Additional usage rights...........................................................................................................................................................179
LiveCycle Reader Extensions.................................................................................................................................................180
Writing JavaScript for Acrobat Reader...............................................................................................................................180
Enabling collaboration............................................................................................................................................................182
1 Interacting with Databases.....................................................................................................184
About ADBC................................................................................................................................................................................184
Establishing an ADBC connection.......................................................................................................................................185
Executing SQL statements.....................................................................................................................................................187
1 SOAP and Web Services ..........................................................................................................189
Using SOAP and web services..............................................................................................................................................189
Using a WSDL proxy to invoke a web service...........................................................................................................190
Synchronous and asynchronous information exchange.....................................................................................191
Establishing a synchronous connection...............................................................................................................192
Asynchronous web service calls..............................................................................................................................194
Using document/literal encoding.................................................................................................................................195
Exchanging file attachments and binary data..........................................................................................................195
Adobe Acrobat SDK
Developing Acrobat® Applications Using JavaScript 9
Converting between string and readstream information....................................................................................196
Accessing SOAP version information..........................................................................................................................197
Accessing SOAP header information...........................................................................................................................197
Authentication.....................................................................................................................................................................198
Error handling......................................................................................................................................................................198
DNS service discovery..............................................................................................................................................................198
Managing XML-based information.....................................................................................................................................200
Workflow applications.............................................................................................................................................................202
1 Interfacing with 3D JavaScript...............................................................................................203
Basic concepts............................................................................................................................................................................203
Getting the Annot3D object of the 3D annotation.......................................................................................................204
Annot3D properties...........................................................................................................................................................204
Acquiring the JavaScript 3D engine.............................................................................................................................205
Using the default script of a 3D annotation....................................................................................................................206
Initializing upon activation....................................................................................................................................................207
Index.........................................................................................................................................210
List of Examples
Example: Test a regular expression in the JavaScript Debugger Console............................................................................24
Example: Executing privileged methods..........................................................................................................................................46
Example: Creating a document with content.................................................................................................................................50
Example: Creating a new document from two other documents...........................................................................................51
Example: Combining several PDF files..............................................................................................................................................51
Example: Combining several files of different formats................................................................................................................51
Example: Extracting and saving pages..............................................................................................................................................52
Example: Saving form data to and reading form data from an attachment........................................................................53
Example: Accessing an XML attachment using E4X.....................................................................................................................53
Example: Set up booklet printing for right-side binding of text and print..........................................................................64
Example: Print booklet in duplex mode, printing only the front pages................................................................................64
Example: Custom script for a combo box.........................................................................................................................................78
Example: Accessing a list from another field...................................................................................................................................80
Example: Accessing individual radio button widgets..................................................................................................................80
Example: Counting the number of widgets in a radio button field........................................................................................81
Example: Inputting numbers and checking the range in a text field.....................................................................................83
Example: Calculating the average of several text fields..............................................................................................................84
Example: Highlighting required fields...............................................................................................................................................85
Example: Inserting navigation buttons on each page.................................................................................................................89
Example: Detecting and classifying XML forms in batch.........................................................................................................104
Example: Customizing the number of repetitions for playback...........................................................................................124
Example: Running openPlayer with settings and events as a rendition action..............................................................127
Example: Play a clip in full screen.....................................................................................................................................................128
Example: Playing a rendition in a screen annotation from a form button........................................................................129
Example: Playing a media clip from a URL....................................................................................................................................129
Example: Playing a media clip from a file......................................................................................................................................130
Example: Playing a sound clip from a URL....................................................................................................................................130
Example: Adding a menu item..........................................................................................................................................................132
Example: Installing and uninstalling a toolbar............................................................................................................................133
Example: Add navigation links to the document.......................................................................................................................139
Example: Setting full screen preferences and resetting them...............................................................................................143
Example: Adding page transitions...................................................................................................................................................144
Example: Creating a rollover effect..................................................................................................................................................147
Example: Toggling a PDF layer..........................................................................................................................................................148
Example: Gathering personal data using templates.................................................................................................................152
Example: Certification signature.......................................................................................................................................................167
Example: Assigning a name to a 3D annotation.........................................................................................................................204
10