Chapter 13

Rights-Enabled PDF Files. 227
Chapter Goals.227 Contents.227

Introduction.227

Additional Usage Rights.228
LiveCycle Reader Extensions.229 Writing Acrobat JavaScript for Reader.229 Enabling Collaboration.233

Chapter 14

Interacting with Databases. 235
Chapter Goals.235 Contents.235

Introduction.235

Introduction to ADBC.236 Establishing an ADBC Connection.236 Executing SQL Statements.239

Chapter 15

SOAP and Web Services. 241
Chapter Goals.241 Contents.242

Introduction.241

Using SOAP and Web Services.242 Using a WSDL Proxy to Invoke a Web Service.243 Synchronous and Asynchronous Information Exchange.245 Using Document/Literal Encoding.249 Exchanging File Attachments and Binary Data.250 Converting Between String and ReadStream Information.251 Accessing SOAP Version Information.252 Accessing SOAP Header Information.252 Authentication.253 Error Handling.253 DNS Service Discovery.254 Managing XML-based Information.256 Workflow Applications.258
Appendix A A Short Acrobat JavaScript FAQ
Where can JavaScripts be found and how are they used?.259 How should I name my Acrobat form fields?.259 How do I use date objects?.261 Converting from a Date to a String.261 Converting from a string to a date.262 Date arithmetic.263
How can I make restricted Acrobat JavaScript methods available to users?.264 How can I make my documents accessible?.265 Document Metadata.265 Short Description.265 Setting Tab Order.265 Reading Order.266 How can I define global variables in JavaScript?.266 Making Global Variables Persistent.266 How can I hide an Acrobat form field based on the value of another?.267 How can I query an Acrobat form field value in another open form?.267 How can I intercept keystrokes one by one as they occur in Acrobat forms?.267 How can I construct my own colors?.268 How can I prompt the user for a response in a dialog?.268 How can I fetch an URL from JavaScript?.268 How can I determine if the mouse has entered/left a certain area on an Acrobat form?.268 How can I disallow changes in scripts contained in my document?.269 How can I hide scripts contained in my document?.269

Index. 271

Preface

Introduction

Welcome to the Adobe Acrobat JavaScript Scripting Guide. This scripting guide is designed to provide you with an overview of how you can use Acrobat JavaScript to develop and enhance standard workflows, such as:
Printing and viewing Spell-checking Stamping and watermarking Managing document security and rights Accessing metadata Facilitating online collaboration Creating interactive forms Customizing interaction with Web Services Interacting with databases
Here you will find detailed information and examples of what the Acrobat JavaScript capabilities are and how to access them, as well as descriptions of the usage of the SDK tools. Acrobat JavaScript is a powerful means by which you can enhance and extend both Acrobat and PDF document functionality.

C:\templates\mytmpl.fm

These are variable declarations:
AVMenu commandMenu,helpMenu;
The GetExtensionID method. The enumeration terminates if proc returns false.
ACCB1 void ACCB2 ExeProc(void) { do something } AFSimple_Calculate(cFunction, cFields)
The Adobe Solutions Network URL is: http://partners.adobe.com/asn/ See Using the SDK. Test whether an ASAtom exists. The setpagedevice operator
The File menu Acrobat Core API Overview User space specifies coordinates for. filename deletefile

Related Documents

This guide refers to the following sources for additional information about Acrobat JavaScript and related technologies:
Acrobat JavaScript Scripting Reference This document is the companion reference to this scripting guide. It provides detailed descriptions of all the Acrobat JavaScript objects. Adobe Acrobat Help This online document is included with Acrobat. Acrobat Solutions Network http://partners.adobe.com/asn/ PDF Reference Guide to SDK Samples Developing for Adobe Reader
If, for some reason, you did not install the entire Acrobat SDK and you do not have all the documents, please visit the Adobe Solutions Network Web site to find the documents you need.

Chapter Goals

Acrobat JavaScript Overview
This chapter introduces the Acrobat JavaScript objects and containment hierarchies, as well as the primary Acrobat and PDF capabilities related to Acrobat JavaScript usage.
At the end of this chapter, you will be able to:
List the Acrobat JavaScript objects and describe their purposes. Describe how Acrobat JavaScript can be used to extend the functionality of Acrobat. Identify the primary workflows that may be achieved with Acrobat JavaScript.
Topics Acrobat JavaScript Introduction Acrobat JavaScript Object Summary What Can You Do with Acrobat JavaScript?
Acrobat JavaScript Introduction
Most people know Acrobat as a medium for exchanging and viewing electronic documents easily and reliably, independent of the environment in which they were created. However, Acrobat provides far more capabilities than a simple document viewer. You can enhance a PDF document so that it contains form fields to capture user-entered data as well as buttons to initiate user actions. This type of PDF document can replace existing paper forms, allowing employees within a company to fill out forms and submit them via PDF files, and connect their solutions to enterprise workflows by virtue of their XML-based structure and the accompanying support for SOAP-based Web Services. Acrobat also contains functionality to support online team review. Documents that are ready for review are converted to PDF. When a reviewer views a PDF document in Acrobat and adds comments to it, those comments (or annotations) constitute an additional layer of information on top of the base document. Acrobat supports a wide variety of standard comment types, such as a note, graphic, sound, or movie. To share comments on a document with others, such as the author and other reviewers, a reviewer can export just the comment "layer" to a separate comment repository. In either of these scenarios, as well as others that are not mentioned here, you can customize the behavior of a particular PDF document, implement security policies, interact with databases and web services, and dynamically alter the appearance of a PDF document by using Acrobat JavaScript. You can tie Acrobat JavaScript code to a specific PDF document, a particular page within a PDF document, or a form field or button in a PDF file. When an end user interacts with Acrobat or a PDF file displayed in Acrobat that contains JavaScript, Acrobat monitors the interaction and executes the appropriate JavaScript code. Not only can you customize the behavior of PDF documents in Acrobat, but you can customize Acrobat itself. In earlier versions of Acrobat (prior to Acrobat 5), this type of customization could only be done by writing Acrobat plug-ins in a high-level language like C or C++. Now, much of that same functionality is available through Acrobat JavaScript extensions. You will find that using Acrobat JavaScript to perform a task such as adding a menu to Acrobats user interface is much easier to do than writing a plug-in. Acrobat JavaScripts can be created for batch processing of multiple documents, processing within a single document, processing for a given page, and processing for a single form field. For batch processing, it is possible to execute JavaScript on a set of PDF files, which enables tasks such as extracting comments from a comment repository, identifying spelling errors, and automatically printing PDF files.

FIGURE 2.2 Console window in the JavaScript Debugger
3. Click Clear (the trash can icon), located at the bottom right of the console, to delete any contents that appear in the window. 4. Type the following code into the console:

var jsNum = 10;

5. With the mouse cursor positioned somewhere in this line of code, press Enter on the numeric keypad or Ctrl+Enter on the regular keyboard to evaluate the code. You should see the results shown in Figure 2.3 below.

FIGURE 2.3

Evaluating the variable declaration
After each Acrobat JavaScript statement executes, the console window prints out undefined, which is the return value of the statement. Note that the result of a statement is not the same as the value of an expression within the statement. In this case, the return value undefined does not mean that the value of jsNum is undefined; it just means that the entire JavaScript statements value is undefined. 6. A more convenient way to evaluate the jsNum variable is to highlight the variable name and execute it as a JavaScript expression, as shown below in Figure 2.4.
FIGURE 2.4 Evaluating jsNum
7. Click the Close button to exit the console and debugger, as shown in Figure 2.5 below:
FIGURE 2.5 Console and Debugger Close Button
Using a JavaScript Editor
There are several ways to invoke the Arobat JavaScript Editor. To begin with, it is possible to select JavaScripts from the Advanced menu and choose one of the following options:
Edit all JavaScripts. Document JavaScripts. Set Document Actions.
A more basic approach, however, is to think of a JavaScript as an action associated with a part of the document, such as a page, bookmark, or form field. It would then make sense to select the object of interest and edit its particular JavaScript. For example, the following are the steps to write a JavaScript for a bookmark: 1. Right-click a bookmark. This triggers a context menu. 2. Select Properties and choose the Actions tab, as shown below in Figure 2.6.

FIGURE 2.6

Bookmark Properties
3. The Select Action drop-down list contains all the possible actions that can be associated with the object, such as Run a JavaScript, Go to view, or Execute a menu item. 4. Select Run a JavaScript from the Select Action drop-down list. 5. Click Add to open the JavaScript editor. 6. In the editor window, write the JavaScript code to be run when the user opens the page.
7. When the code is complete, click Close to close the editor. If there are errors in your code, the JavaScript editor highlights the code line in question and display an error message, as shown below in Figure 2.7.
FIGURE 2.7 Error detected by the JavaScript Editor
In Figure 2.7, the quotation mark to the right of the string is missing.
JavaScript actions have a scope associated with various levels of objects in a PDF document, such as a form field, a page, or the entire document. For example, a script at the document level would be available from all other scriptable locations within the document.

var myDoc = app.newDoc();
Once this statement has been executed, you may add content by invoking methods contained within the doc object, as indicated below in Table 4.1:
TABLE 4.1 Acrobat JavaScript Usage for Creating Content in a PDF Document
Content page page annot field icon link

Object

Methods
doc template doc doc doc doc
newPage, insertPages, replacePages spawn addAnnot addField addIcon addLink addScript addThumbnails createChild, insertChild addWebLinks createTemplate
document-level doc JavaScript thumbnails bookmark web link template
doc doc.bookmarkRoot doc doc

Combining PDF Documents

You can take advantage of Acrobat JavaScript to customize and automate the process of combining PDF documents. If you would like to combine multiple PDF files into a single PDF document, you may do so through a series of calls to the doc objects insertPages method. For example, the following code creates a new document that is composed from two other documents:
// Create a new PDF document: var newDoc = app.newDoc(); // Insert doc1.pdf: newDoc.insertPages({ nPage : -1, cPath : "/c/doc1.pdf", }); // Insert doc2.pdf: newDoc.insertPages({ nPage : newDoc.numPages, cPath : "/c/doc2.pdf", }); // Save the new document: newDoc.saveAs({ "/c/myNewDoc.pdf"); }); // Close the new document without notifying the user: newDoc.closeDoc(true);
Creating PDF Files from Multiple Files
It is possible to dynamically add content from other sources into a new PDF file. The sources may include files whose types conform to Multipurpose Internet Mail Extensions (MIME) type definitions. One simple approach would be to invoke the app objects openDoc method to convert and open other files with supported formats, and then save or combine files as a PDF document. Another way to import an external file into a PDF document is to invoke the doc objects importDataObject method. After doing this, it is possible to extract information from the external file for placement and presentation within the PDF document. For example, the following code illustrates how to import an XML file and extract its content:

In the next example, the addWatermarkFromFile method is used to add the second page of watermark.pdf as a watermark to the first 10 pages of the current document. It is rotated counterclockwise by 45 degrees, and positioned one inch down and two inches over from the top left corner of each page:
this.addWatermarkFromFile({ cDIPath: "/C/watermark.pdf", nSourcePage: 1, nEnd: 9, nHorizAlign: 0, nVertAlign: 0, nHorizValue: 144, nVertValue: -72, nRotation: 45 });
Converting PDF Documents to XML Format
It is also possible to use the addWatermarkFromText method to create watermarks. In this next example, the word Confidential is placed in the center of all the pages of the document, and its font helps it stand out:
this.addWatermarkFromText( "Confidential", 0, font.Helv, 24, color.red );
Adding Headers and Footers
As you learned in Adding Watermarks and Backgrounds, you may use Acrobat JavaScripts watermarking functionality to add headers and footers to your documents by invoking the doc objects addWatermarkFromText method, which can be applied as a header or footer by specifying the placement of the text at the top or bottom of the page. The following example places a multiline header, one inch down and one inch over from the top right corner of all the pages within the current document:
this.addWatermarkFromText({ cText: "Confidential Document", nTextAlign: 2, nHorizAlign: 2, nVertAlign: 0, nHorizValue: -72, nVertValue: -72 });
Since XML is often the basis for information exchange within Web Services and enterprise infrastructures, it may often be useful to convert your PDF documents into XML format. It is a straightforward process to do this using the doc objects saveAs method, which not only performs the conversion to XML, but also to a number of other formats. In order to convert your PDF document to a given format, you will need to determine the device-independent path to which you will save your file, and the conversion ID used to save in the desired format. A list of conversion IDs for all formats is provided in the ASN documentation. For XML, the conversion ID is "com.adobe.acrobat.xml-1-00". The following code converts the current PDF file to C:\test.xml: this.saveAs("/c/test.xml", "com.adobe.acrobat.xml-1-00");

Print Production

This chapter will provide you with an in-depth understanding of the ways in which you may manage print production workflows for PDF documents.
Use Acrobat JavaScript to automate and control print quality. Determine whether a file will be sent to a printer or a PostScript file. Control how PDF layers are printed.
Topics Printing PDF Documents Printing Documents with Layers Setting Advanced Print Options
Since printing involves sending pages to an output device, there are many options that can affect print quality. Acrobat JavaScript can be used to enhance and automate the use of these options in print production workflows, primarily through the use of the printParams object, whose properties and methods are described below in Table 5.1:

About PDF Forms

Types of PDF Forms There are two types of PDF forms: Acrobat forms and XML forms. 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 in data, the information within the PDF 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. If you are creating a new form, the most recommended type is a XML form since its format readily allows for Web service interactions and compatibility with document processing needs within enterprise-wide infrastructures. The new Adobe XML forms 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. Static XML forms were supported in Acrobat 6.0, and dynamic XML forms are now supported in Acrobat 7.0. Both types are created using Adobe LiveCycle Designer. 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 dialogs. Finally, the Acrobat 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 may 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.

Reviewing Documents with Additional Usage Rights
For email-based reviews, the specification of additional usage rights within a document enables extra capabilities within Adobe Reader. This enables the reviewer to add comments, import and export form-related content, save the document, or apply a digital signature. For example, when using the doc objects encryptForRecipients method, you may specify the following permissions for reviewers:
allowAll: permits full and unrestricted access to the entire document. allowAccessibility: permits content accessed for readers with visual or motor

impairments.

allowContentExtraction: permits content copying and extraction. allowChanges: permits either no changes, or changes to part or all of the document
assembly, content, forms, signatures, and notes.
allowPrinting: permits no printing, low-quality printing, or high-quality printing.
The following code allows full and unrestricted access to the entire document for one set of users (importantUsers), and allows high quality printing for another set of users (otherUsers):
var sh = security.getHandler("Adobe.PPKMS"); var dir = sh.directories[0]; var dc = dir.connect(); dc.setOutputFields({oFields:["certificates"]}); var importantUsers = dc.search({oParams:{lastName:"Smith"}}); var otherUsers = dc.search({oParams:{lastName:"Jones"}}); this.encryptForRecipients({ oGroups:[ { oCerts: importantUsers, oPermissions: { allowAll: true } }, { oCerts: otherUsers, oPermissions: { allowPrinting: "highQuality" } } ], bMetaData: true });

Emailing PDF Documents

In addition to the Email options available in the Acrobat menu and toolbar, it is also possible to use Acrobat JavaScript to set up an automated email review workflow. This may be done through the doc objects mailDoc method. In the code shown below, the document is automatically sent to recipient@adobe.com:
this.mailDoc( false, "recipient@adobe.com", "", "", "Review", "Please review this document and return. Thank you." );
For Windows systems, the default mail program must be MAPI-enabled.
Acrobat JavaScript-based Collaboration Driver
Acrobat JavaScript can be used to describe the workflow for a given document review, and can be used in review management. This is done by specifying a state model for the types of annotations a reviewer may use and creating an annotation store on the server for customized comment and review within browser-based workflows. The Collab object provides you with control over the possible states annot objects may have, and may be used in conjunction with the SOAP object to create an annotation store. There are several methods available within the Dollab object that enable you to describe the state model for the review: these include addStateModel, getStateInModel, transitionToState, and removeStateModel. The addStateModel method is used to add a new state model to Acrobat describing the possible states for an annot object using the model, and the removeStateModel method removes the model, though it does not affect previously created annot objects. Their usage is shown in the code below:

Changing Colors, Icons, and Other Comment Properties
You may use Acrobat JavaScript to change the properties of any type of annotation. To change the background color of a comment, assign a new value to its fillColor property. To change the icon, assign a value to its attachIcon, noteIcon, or soundIcon property. All the comment properties are available through the annot object, and may be set by invoking its setProps method.

Adding Watermarks

A watermark is an area containing text or graphics appearing underneath or over existing document content when a document is printed. This is often referred to as layered content, and may appear differently in print than it does on the screen. For example, the word "Confidential" could appear as a watermark within a document. You can add watermarks through Acrobat JavaScript by invoking the doc objects addWatermarkFromFile or addWatermarkFromText method, and you may also create stamp annotations. The addWatermarkFromFile method places, into a specified location and at a particular scale factor and rotation, a single page from any document format that Acrobat can convert to PDF (such as JPEG, PNG, TIFF, Word, or AutoCAD). The Stamping User Interface You may create an annotation using the Stamp type, and invoke the annot objects AP property to determine the appearance of the stamp in the document. The following appearance options are available for stamp annotations:

Approved AsIs Confidential Departmental Draft Experimental Expired Final ForComment ForPublicRelease NotApproved NotForPublicRelease Sold TopSecret
For example, the following code adds an "Approved" stamp to the document:
var annot = this.addAnnot({ page: 0, type: "Stamp", author: "Me", name: "myStamp", rect: [400,400,550,500], contents: "Good work!", AP: "Approved" });
Header and Footer Functionality You may use Acrobat JavaScript to add headers and footers to your documents. For example, you may use the doc objects addWatermarkFromText method, which has several properties useful for this specific purpose:
cText: The actual text displayed in the header or footer. nTextAlign: How the text is aligned in the header or footer. vTextAlign: How the watermark is aligned vertically: a value of 0 aligns it at the top
of the page (header), and a value of 2 aligns it at the bottom of the page (footer).
nStart: The starting page for the watermark. A value of -1 causes the resultant header or footer to appear on every page of the document.

var ocgArray = this.getOCGs(3);

Navigating with Layers

Since information can be stored in different layers of a PDF document, navigational controls can be customized within different layers, whose visibility settings may be dynamically customized so that they are tied to context and user interaction. For example, if the user selects a given option, a set of navigational links belonging to a corresponding optional content group may be shown. In addition, it is possible to determine the order in which layers are displayed in the user interface by invoking the doc objects getOCGOrder and setOCGOrder methods. In the following example, the display order of all the layers is reversed:
var ocgOrder = this.getOCGOrder(); var newOrder = new Array(); for (var i=0; i<ocgOrder.length; i++) newOrder[i] = ocgOrder[ocgOrder.length - i - 1]; this.setOCGOrder(newOrder);
Editing the Properties of PDF Layers
The OCG object provides properties that can be used to determine whether the objects default state should be on or off, whether its intent should be for viewing or design purposes, whether it should be locked, the text string seen in the user interface, and the current state. The properties are shown below in Table 10.15:
TABLE 10.15 OCG Properties
Description Determines whether the OCG object is on or off by default The intent of the OCG object (View or Design) Whether the on/off state can be toggled through the user interface The text string seen in the user interface for the OCG object The current on/off state of the OCG object
initState intent locked name state
The initState property can be used to set the default state for an optional content group. In the following example, myLayer is set to on by default:
myLayer.initState = true;
The intent property, which is an array of values, can be used to define the intent of a particular optional content group. There are two possible values used in the array: View and Design. A Design layer is created for informational purposes only, and does not affect the visibility of content. Its purpose is to represent a document designers structural organization of artwork. The View layer is intended for interactive use by document consumers. If View is used, the visibility of the layer is affected. In the following example, the intent of all the OCG objects in the document is set to both values:
var ocgs = this.getOCGs(); for (var i=0; i<ocgs.length; i++) ocgs[i].intent = ["View", "Design"];
The locked property is used to determine whether a given layer can be toggled through the user interface. In the following example, myLayer is locked, meaning that it cannot be toggled through the user interface:

myLayer.locked = true;

binary issuerDN keyUsage MD5Hash SHA1Hash serialNumber subjectCN subjectDN usage ubrights
Digitally Signing PDF Documents
Security Policies Security policies are common specifications that include the type of encryption, the permission settings, and the password or public key to be used. You may create folder-level scripts containing objects that reflect these policies. Security policies may be customized through the use of securityPolicy objects, which may be accessed and managed by the security objects getSecurityPolicies and chooseSecurityPolicy methods, as well as the doc objects encryptUsingPolicy method. Secure Forms You can lock form fields by creating a script containing a call to the signature fields setLock method, and passing that script as the second parameter to the signature fields setAction method. In addition, you may sign an embedded FDF data object by invoking its signatureSign method, and subsequently validate the signature by invoking its signatureValidate method.
A digital signature contains identifying information about the person signing the document. When applying an author signature (the first time a signature is applied to a document), it is also possible to certify the document. This involves providing a legal attest with regard to the documents contents and specifying the types of changes allowed for the document in order for it to remain certified.

Signing a PDF Document

To sign a document, create a signature field, choose a security handler, and invoke the fields signatureSign method, which accepts the following parameters:
oSig: the security handler object oInfo: a signatureInfo object cDIPath: the device-independent path to which the file will subsequently be saved bUI: whether the security handler will display a user interface when signing cLegalAttest: a string explaining legal warnings (for author signatures only)
The creation and usage of these parameters are explained below in the following sections: The Security Handler Object, The SignatureInfo Object, and Applying the Signature.
The Security Handler Object To obtain a security handler (the oSig parameter), invoke the security objects getHandler method, which creates a new security handler engine, and accepts the following parameters:
cName: the name of the security handler (contained in the security objects handlers property) bUIEngine: the existing engine associated with the Acrobat user interface
The following code illustrates how to set up signature validation whenever the document is opened, lists all available security handlers, and selects the Adobe.PPKLite engine associated with the Acrobat user interface:
// Validate signatures when the document is opened: security.validateSignaturesOnOpen = true; // List all the available signature handlers for (var i=0; i<security.handlers.length; i++) console.println(security.handlers[i]); // Select the Adobe.PPKLite engine with Acrobat user interface: var ppklite = security.getHandler("Adobe.PPKLite", true);

Encrypting PDF Files for a List of Recipients
As you have seen throughout this chapter, the doc objects encryptForRecipients method is the primary means of encrypting PDF files for a list of recipients using Acrobat JavaScript. In the previous example, the certificates used were gathered by connecting to a directory, which is a repository of user information. The directory object contains an info property with which it is possible to create and activate a new directory, and is accessible either through the directories property or the newDirectory method of the securityHandler object. The info object is a DirectoryInformation object, which may contain standard properties related to the name of the directory, as well as additional properties specific to a particular directory handler (these may include server and port information). To create a new directory, create a DirectoryInformation object, obtain a securityHandler object and invoke its newDirectory method, and assign the DirectoryInformation object to the new directorys info property. An example of this is given below:
// Create and activate a new directory: var newDirInfo = { dirStdEntryID: "dir0", dirStdEntryName: "Employee LDAP Directory", dirStdEntryPrefDirHandlerID: "Adobe.PPKMS.ADSI", dirStdEntryDirType: "LDAP", server: "ldap0.acme.com", port: 389 }; // Obtain the security handler: var sh = security.getHandler("Adobe.PPKMS"); // Create the new directory object: var newDir = sh.newDirectory(); // Store the directory information in the new directory: newDir.info = newDirInfo;
In order to obtain certificates from a directory, you must first connect to it using the directory objects connect method, which returns a DirConnection object. An example is given below:
// Obtain the security handler: var sh = security.getHandler("Adobe.PPKMS"); var dc = sh.directories[0].connect();
It is then possible to use the DirConnection object to search for certificates. You can specify the list of attributes to be used for the search by invoking the DirConnection objects setOutputFields method, which accepts two parameters:
oFields: an array of attributes to be used in the search bCustom: whether the attributes are standard output attribute names For example, the following code specifies standard output attributes (certificates and email):
dc.setOutputFields({oFields: ["certificates", "email"]});
To perform the search, invoke the DirConnection objects search method, which accepts the following parameters:
oParams: an array of key-value pairs consisting of search attribute names and their corresponding strings cGroupName: the name of the group to which to restrict the search bCustom: whether oParams contains standard attribute names bUI: whether a user interface is used to collect the search parameters

Assume that the namespace is http://mydomain/methods, the method name is echoString, and it accepts a string parameter called inputString. The following code represents the oRequest parameter:
var echoStringRequest = { "http://mydomain/methods:echoString { inputString: "This is a test." } };
The cAction parameter contains header information described by the WSDL document that is used by firewalls to filter SOAP requests. In our example, we will supply the location of the WSDL document:
var mySOAPAction = "http://mydomain/methods";
We may now invoke the echoString web method:
var response = SOAP.request ({ cURL: myURL, oRequest: echoStringRequest, cAction: mySOAPAction });
In the case of synchronous requests such as this one, the value returned by the request method (response in this example) is an object containing the result of the web method, which will be one of the Acrobat JavaScript types corresponding to XSD types. The default format for the response value is an object describing the SOAP body (or header) of the returned message.
In the case of base64 or hex encoding of binary information, the type returned will be a readStream object.
We may now obtain the returned value by using syntax that corresponds to the SOAP body sent back by the web method:
var responseString = "http://mydomain/methods:echoStringResponse"; var result = response[responseString]["return"]; // Display the response in the console: console.println("Result is " + result);
Similarly, we can invoke the echoInteger method. To do this, we will use the same value for the cURL and cAction parameters, and develop an oRequest parameter like the one we used for the echoString method. In this case, however, we must supply an XSDcompliant object to represent the integer value:
var myIntegerObject = { soapType: "xsd:int", soapValue: "10" }; var echoIntegerRequest = { "http://mydomain/methods:echoInteger { inputInteger: myIntegerObject } };
Now we may invoke the echoInteger web method and display its results:
var response = SOAP.request ({ cURL: myURL, oRequest: echoIntegerRequest, cAction: mySOAPAction }); var responseString = "http://mydomain/methods:echoIntegerResponse"; var result = response[responseString]["return"]; // Display the response in the console: console.println("Result is " + result);

usage rights 27, 211 UserEntity 203 Util 23
Node 112 parse 256 Schema Definition Language 241 XMLData 256 XMP metadata 199 XPath 24, 112 XSL transform 112

zoom type 183

validation 101 viewing modes 182 full screen 182 regular 182
watches list 57 watermark 134 web method 244 web services 20, 24, 75, 86, 87, 241, 242 Web Service Security 253 Web Services Description Language 241 What Can You Do with Acrobat JavaScript? 19 Windows certificate security 223 workflows 26 WSDL 24, 241 proxy 243
XDP 115 XFA 109 appModel 109 DOM 112 Tree 112 treeList 112 XFDF 115 XML 24, 67, 75, 112, 241 applyXPath 256 DOM 112 forms 85, 87

1": -1, 2": -2,
1": -3, 2": -4,
} }, "Chapter 3": -5, "Chapter 4": -6 } }) }, subl: function(dialog) { console.println("Selection Box Hit"); }, getHierChoice: function (e) { if (typeof e == "object") { for ( var i in e ) { if ( typeof e[i] == "object" ) { var retn = this.getHierChoice(e[i]); if ( retn ) { retn.label = i + ", " + retn.label; return retn; } // if e[i] > 0, weve found the selected item } else if ( e[i] > 0 ) return { label:i, value: e[i] }; } } else { if ( e[i] > 0 ) return e[i]; } }, butn: function (dialog) { var element = dialog.store()["subl"] var retn = this.getHierChoice(element); if ( retn ) { // write to the console the full name of the item selected console.println("The selection you've chosen is \"" + retn.label + "\", its value is " + retn.value ); dialog.end("ok"); // this.doc is the doc object of this document this.doc.gotoNamedDest("dest"+retn.value); } else app.alert("Please make a selection, or cancel"); }, cncl: function (dialog) { dialog.end("cancel") }, // Dialog Description description: { name: "My Novel", elements: [ { type: "view", align_children: "align_left",
elements: [ { type: "cluster", name: "Book Headings", elements: [ { type: "static_text", name: "Make a selection", }, { type: "hier_list_box", item_id: "subl", char_width: 20, height: 200 } ] }, { type: "view", align_children: "align_row", elements: [ { type: "button", item_id: "cncl", name: "Cancel" }, { item_id: "butn", type: "button", name: "Select" } ] } ] } ] } };
This function attaches the document object to the dialog, then passes the dialog to the app.execDialog method. The dialog4 object and this function can be at the document level.
function dotheDialog(dialog,doc) { dialog.doc = doc; var retn = app.execDialog( dialog )
Finally, the following script can be executed from a mouse-up action, for example.
dotheDialog( dialog4, this );
Example 5 See Example 2 on page 136, which shows how to execute privileged code from a nonprivileged context.

cMimeType

(optional) An optional MIME type such as audio/wav. If cMimeType is omitted, the list includes all available players. If cMimeType is specified, the list includes only players that can handle that MIME type.
Returns PlayerInfoList Object Example 1 List MP3 players to the debug console.
var mp = app.media.getPlayers("audio/mp3") for ( var i = 0; i < mp.length; i++) { console.println("\nmp[" + i + "] Properties"); for ( var p in mp[i] ) console.println(p + ": " + mp[i][p]); }
Example 2 Choose any player that can play Flash media by matching the MIME type. The code assumes the code below is executed as a Rendition action with associated rendition (so no arguments for createPlayer are required).
var player = app.media.createPlayer(); player.settings.players = app.media.getPlayers( "application/x-shockwave-flash" ); player.open();

getPlayerStockEvents

6.0 Returns an Events Object containing the stock EventListeners required in a media player for normal playback in Acrobat. The stock EventListeners provide standard Acrobat behavior such as focus handling. Use MediaPlayer.events.add to add these stock events to a media player. The app.media.createPlayer and app.media.openPlayer methods automatically call getPlayerStockEvents internally, so it is not necessary to call this method yourself unless you are writing code that sets up all EventListeners explicitly. If app.media.trace is true, debug trace listeners are also included with the stock EventListeners.

Returns Events Object

A MediaSettings Object.

getPlayerTraceEvents

6.0 Returns an Events Object containing EventListeners that provide a debugging trace as events are dispatched. Parameters None Returns An Events Object

getRenditionSettings

6.0 Calls Rendition.select to get a MediaSelection Object, then MediaSelection.rendition.getPlaySettings to get a MediaSettings Object for playback. If either of these fails, it calls the getAltTextSettings method to get a MediaSettings Object for alternate text playback. Finally, it returns the resulting MediaSettings Object, or null if getAltTextSettings returned null (that is, alternate text was not specified or not allowed). Parameters

A PlayerArgs Object.

MediaSettings Object or null Example See Example 3 on page 162.

Returns Nothing Example 1 Some script is run and an exception is thrown due to some error. A breakpoint is programmatically set using the information given in the error message.
SyntaxError: missing ; before statement 213:Document-Level: myDLJS // now set a breakpoint using the console dbg.sb({ fileName: "Document-Level: myDLJS", lineNum: 213, condition: "true" });
Example 2 This example simulates the functionality of the Store breakpoints in PDF file check box in the JavaScript user preferences.
// save breakpoints in PDF file this.addScript("myBreakpoints", "var myBPS = " + dbg.bps.toSource()); // now reset the breakpoints for ( var i = 0; i < myBPS.length; i++ ) dbg.sb( myBPS[i] );
Example 3 Set a conditional break. Consider the following code, which is a mouse-up action.
for (var i=0; i<100; i++) myFunction(i);
// defined at document level
// In the console, set a conditional break. Here, we break when the // index of the loop is greater than 30. dbg.sb({ fileName:"AcroForm:Button1:Annot1:MouseUp:Action1", lineNum:2, condition:"i > 30" })
The si (step in) method advances the program pointer to the next instruction in the JavaScript program, entering each function call for which there is a script defined. (Native JavaScript calls cannot be stepped into.)
The sn (step instruction) method advances the program pointer to the next bytecode in the JavaScript program. (Each JavaScript instruction is made up of several bytecodes as defined by the JavaScript interpreter.)
The so (step out) method executes the program until it exits the current function. Execution stops at the instruction immediately following the call to the current function. If
the scope currently under debug is the top-level scope, the program either continues executing until it ends or stops again when it reaches a breakpoint. Parameters None Returns Nothing
The sv (step over) method advances the program pointer to the next instruction in the JavaScript program. If a function call is encountered, the debugger does not step into the instructions defined inside that function.

Dialog Object

D i a l og O b je c t
An instance of this object is passed as a parameter to dialog handlers (see Dialog Handlers on page 97). These handlers include the initialize, validate, commit, destroy and ItemID methods of the dialog descriptor object literal that is passed to app.execDialog. The Dialog object allows the current state of the Dialog to be queried and set.

Returns If cPath is not specified, returns the Document Object for the new document; otherwise, returns the null object. Example The following batch sequence takes each of the selected files, extracts each page, and save the page in a folder with a unique name. It could be used, for example, when the clients one-page bills are produced by an application and placed in a single PDF file. The client wants to separate the pages for distribution or separate printing jobs.
/* Extract Pages to Folder */ // regular expression used to acquire the base name of file var re = /\.pdf$/i; // filename is the base name of the file Acrobat is working on var filename = this.documentFileName.replace(re,"");
try {for (var i = 0; i < this.numPages; i++) this.extractPages({ nStart: i, cPath: "/F/temp/"+filename+"_" + i +".pdf" }); } catch (e) { console.println("Aborted: " + e) }

flattenPages

Converts all annotations in a page range to page contents. If a page range is not specified, all annotations in the document are converted.
Great care must be used when using this method. All annotationsincluding form fields, comments, and linkson the specified range of pages are flattened. They may have appearances, but they will no longer be annotations.
(optional) A 0-based index that defines the start of an inclusive range of pages in the current document. If only nStart is specified, the page range is the single page specified by nStart. (optional) A 0-based index that defines the end of an inclusive range of pages in the current document. (optional, Acrobat 6.0) This parameter determines how to handle nonprinting annotations. Values are 0 (default): Non-printing annotations are flattened. 1: Non-printing annotations are left as is. 2: Non-printing annotations are removed from the document.

nEnd nNonPrint

Returns Nothing Example Flatten all pages in the document.

this.flattenPages();

getAnnot
5.0 Returns an Annotation Object contained on a specific document page.

nPage cName

The page that contains the Annotation Object. The name of the Annotation Object.
The Annotation Object, or null if there is no such annotation. Example
var ann = this.getAnnot(0, "OnMarketShare"); if (ann == null) console.println("Not Found!") else console.println("Found it! type: " + ann.type);

getAnnot3D

The name to associate with the data object. (optional) A device-independent path to a data file on the users hard drive. This path may be absolute or relative to the current document. If not specified, the user is prompted to locate a data file. (optional, Acrobat 6.0) The language-independent name of a crypt filter to use when encrypting this data object. This crypt filter must have previously been added to the documents list of crypt filters, using the Document Object addRecipientListCryptFilter method, otherwise an exception will be thrown. To leave this data object unencrypted in a file that is encrypted by the Document Object encryptForRecipients method, the predefined Identity crypt filter can be used.
true on success. An exception is thrown on failure.
function DumpDataObjectInfo(dataobj) { for (var i in dataobj) console.println(dataobj.name + "[" + i + "]=" + dataobj[i]); } // Prompt the user for a data file to embed.
this.importDataObject("MyData"); DumpDataObjectInfo(this.getDataObject("MyData")); // Embed Foo.xml (found in parent director for this doc). this.importDataObject("MyData2", "./Foo.xml"); DumpDataObjectInfo(this.getDataObject("MyData2"));

importIcon

Imports an icon into the document and associates it with the specified name. See also icons, addIcon, getIcon, removeIcon, field methods buttonGetIcon, buttonImportIcon, buttonSetIcon, and the Icon Object. Beginning with version 6.0, Acrobat will first attempt to open cDIPath as a PDF. On failure, Acrobat will try to convert cDIPath to PDF from one of the known graphics formats (BMP, GIF, JPEG, PCX, PNG, TIFF) and then import the converted file as a button icon.
N O T E S : (SecurityS): If cDIPath is specified, this method can only be executed during
batch, console or menu events. See Privileged versus Non-privileged Context on page 34 for details. The event Object contains a discussion of Acrobat JavaScript events. Parameters
The name to associate with the icon. (optional) A device-independent path to a PDF file on the users hard drive. This path may be absolute or relative to the current document. cDIPath may only be specified in a batch environment or from the console. If not specified, the nPage parameter is ignored and the user is prompted to locate a PDF file and browse to a particular page. (optional) The 0-based index of the page in the PDF file to import as an icon. The default is 0.

The document that this method is being called for does not contain the requested embedded data object. The data object is not a PDF document. Permissions forbid opening attachments by means of JavaScript.
The document should be closed (using closeDoc) after it is no longer needed. Parameters
The name of the data object.
The name of a data object is a property of the Data Object. A name is given to the object when it is embedded, automatically by the Acrobat UI, or programmatically by the JavaScript methods createDataObject or importDataObject. Returns Document Object or an exception is thrown.
Related objects, properties, and methods are dataObjects, setDataObjectContents, getDataObjectContents, createDataObject, and importDataObject, and the Data Object. Example Open a PDF attachment and extract form data from it.
var oDoc = this.openDataObject("myAttachment"); try { var myField = this.getField("myTextField"); // get the value of "yourTextField" in PDF attachment var yourField = oDoc.getField("yourTextField"); // view this value in "myTextField" myField.value = yourField.value; oDoc.closeDoc(); } catch(e) { app.alert("Operation failed");}
See also Example 5 (Acrobat 7.0) on page 318 following the submitForm method.
Prints all or a specific number of pages of the document. Beginning with Acrobat 6.0, the method can print the document using the settings contained in a PrintParams Object, rather than through the other parameters. The permanent print settings are not altered.
N O T E S : (Security S, Acrobat 6.0) When printing to a file, the path must be a safe path (see
Safe Path on page 34). The print method will not overwrite an existing file.
(Security S, Acrobat 7.0) Non-interactive printing can only be executed during batch, console, and menu events. Printing is made non-interactive by setting bUI is to false or by setting the interactive property to silent, for example:
var pp = this.getPrintParams(); pp.interactive = pp.constants.interactionLevel.silent;
Outside of batch, console, and menu events, the values of bUI and of interactive are ignored and a print dialog will always be presented. See also Privileged versus Non-privileged Context on page 34.
N O T E S : On a Windows platform, the file name must include an extension of.ps or.prn
(case insensitive). Additionally, the print method will not create a file directly in the root directory, the windows directory, or the windows system directory. An InvalidArgsError (see Error Object) exception will be thrown and print will fail if any of the above security restrictions are not met.

bUI nStart

(optional) If true (the default), will cause a UI to be presented to the user to obtain printing information and confirm the action. (optional) A 0-based index that defines the start of an inclusive range of pages. If nStart and nEnd are not specified, all pages in the document are printed. If only nStart is specified, the range of pages is the single page specified by nStart. If nStart and nEnd parameters are used, bUI must be false. (optional) A 0-based index that defines the end of an inclusive page range. If nStart and nEnd are not specified, all pages in the document are printed. If only nEnd is specified, the range of a pages is 0 to nEnd. If nStart and nEnd parameters are used, bUI must be false. (optional) If true, suppresses the cancel dialog box while the document is printing. The default is false. (optional, Acrobat 5.0) If true, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If false, it is not. The default is false. (optional, Acrobat 5.0) If true, print pages as an image. The default is false. (optional, Acrobat 5.0) If true, print from nEnd to nStart. The default is false. (optional, Acrobat 5.0) If true (the default), annotations are printed. (optional, Acrobat 6.0) The PrintParams Object containing the settings to use for printing. If this parameter is passed, any other parameters are ignored.

3.01 The target object that triggered the event. In all mouse, focus, blur, calculate, validate, and format events, it is the Field Object that triggered the event. In other events, such as page open and close, it is the Document Object or this Object. Type: object Access: R

targetName

5.0 Tries to return the name of the JavaScript being executed. Can be used for debugging purposes to help identify the code causing exceptions to be thrown. Common values of targetName include:
The folder-level script file name for App/Init events The document-level script name forDoc/Open events The PDF file name being processed for Batch/Exec events The field name for Field events The menu item name for Menu/Exec events. The screen annotation name for Screen events (multimedia events).
When an exception is thrown, targetName is reported if there is an identifiable name. Type: String Example In this example, the first line of the folder-level JavaScript file conserve.js has an error in it. When the viewer starts, an exception is thrown and the message reveals the source of the problem.
MissingArgError: Missing required argument. App.alert:1:Folder-Level:App:conserve.js ===> Parameter cMsg.
5.0 The type of the current event. The type and name together uniquely identify the event. Valid types are:
Batch Console App Doc Page External Bookmark Link Field Menu
3.01 This property has different meanings for different field events:
For the Field/Validate event, it is the value that the field contains when it is committed. For a combo box, it is the face value, not the export value (see changeEx). For example, the following JavaScript verifies that the field value is between zero and 100:
if (event.value < 0 || event.value > 100) { app.beep(0); app.alert("Invalid value for field " + event.target.name); event.rc = false; }
For a Field/Calculate event, JavaScript should set this property. It 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 Field/Format event, JavaScript should set this property. It is the value used when generating the appearance for the field. By default, it contains the value that the user has committed. For a combo box, this is the face value, not the export value (see changeEx for the export value). For example, the following JavaScript formats the field as a currency type of field.
event.value = util.printf("$%.2f", event.value);
For a Field/Keystroke event, it is the current value of the field. If modifying a text field, for example, this is the text in the text field before the keystroke is applied. For Field/Blur and Field/Focus events, it is the current value of the field. During these two events, event.value is read only. That is, the field value cannot be changed by setting event.value. Beginning with Acrobat 5.0, for a list box that allows multiple selections (see field.multipleSelection), the following behavior occurs. If the field value is an array (that is, multiple items are selected), event.value returns an empty string when getting, and does not accept setting. Access: R/W

See MediaPlayer.page and MediaPlayer.triggerGetRect for a variation on this same example.

onPause

6.0 The Pause event is triggered when media playback pauses, either because of user interaction or when the play method is called. See also afterPause (the difference between on and after event methods are explained on page 354). Parameters

onPlay

6.0 The Play event is triggered when media playback starts or resumes, either because of user interaction or when the pause method is called. See also afterPlay (the difference between on and after event methods are explained on page 354).

onReady

6.0 The Ready event is triggered when a newly-created MediaPlayer is ready for use. Most methods of a MediaPlayer Object cannot be called until the Ready event is triggered. See also afterReady (the difference between on and after event methods are explained on page 354). Parameters

onScript

6.0 The Script event is triggered when a script trigger is encountered in the media during playback. See also afterScript (the difference between on and after event methods are explained on page 354). The event object for a Script event includes these properties in addition to the standard event properties:
These two strings can contain any values that the media clip provides. They do not necessarily contain executable JavaScript code and it is up to the onScript or afterScript EventListener to interpet them.

onSeek

6.0 The Seek event is triggered when a MediaPlayer is finished seeking to a playback offset as a result of a seek call. Not all media players trigger Seek events. See also afterSeek (the difference between on and after event methods are explained on page 354). Parameters

onStatus

6.0 The Status event is triggered on various changes of status that a MediaPlayer reports. See also afterStatus (the difference between on and after event methods are explained on page 354). The event Object for a Status event includes these properties in addition to the standard event properties:
The following values are used only by some media players, and only when media.code == app.media.status.buffering. They are zero otherwise.

onStop

6.0 The Stop event is triggered when media playback stops, either because of user interaction or when the stop method is called. See also afterStop (the difference between on and after event methods are explained on page 354). Parameters

Example 2 The following script randomly plays (famous) quotations. The media is an audio clip (.wma) of famous quotations, which does support markers and scripts. The afterReady listener counts the number of markers, one at the beginning of each quotation. At the end of each quotation, there is also an embedded command script. The afterScript listener watches for these commands and if it is a pause command, it pauses the player.
var nMarkers=0; var events = new app.media.Events; events.add({ // count the number of quotes in this audio clip, save as nMarkers afterReady: function() { var g = player.markers; while ( (index = g.get( { index: nMarkers } ) ) != null ) nMarkers++; }, // Each quote should be followed by a script, if the command is to // pause, then pause the player. afterScript: function( e ) { if ( e.media.command == "pause" ) player.pause(); } }); var player = app.media.openPlayer({ rendition: this.media.getRendition( "myQuotes" ), settings: { autoPlay: false }, events: events }); // randomly choose a quotation function randomQuote() { var randomMarker, randomMarkerName; console.println("nMarkers = " + nMarkers); // randomly choose an integer between 1 and nMarkers, inclusive randomMarker = Math.floor(Math.random() * 100) % ( nMarkers ) + 1; // indicate what quotation we are playing this.getField("Quote").value = "Playing quote " + randomMarker; // The marker names are "quote 1", "quote 2", "quote 3", etc. randomMarkerName = "quote " + randomMarker; // see the marker with the name randomMarkerName player.seek( { marker: randomMarkerName } );

player.play(); }

Action is initiated by the mouse-up button action such as
try { randomQuote() } catch(e) {}
6.0 Sets the keyboard focus to the media player and triggers a Focus event (onFocus/afterFocus). If another player or PDF object has the focus, that object receives a Blur event (onBlur/afterBlur). If the media player already has the focus, nothing happens. If the player is not open or not visible, an exception is thrown. Parameters None Returns Nothing Example See Example 1 on page 153 for an example of usage.

events: { afterReady: doAfterReady( e ), onClose: doOnClose( e ), },
Or, if you are creating an HonorsArgs, you can simplify the notation as follows:
events: { Ready: true, Close: true },
playerHonors Function This function is provided as JavaScript source code that can be copied into a PDF file as a document script. It performs the same tests as the honors method in Acrobat 7.0, but it works on Acrobat 6.0 as well. When running on Acrobat 6.0, playerHonors uses hard-coded tests that match the capabilities of the media players shipped with Acrobat 6.0. When running on Acrobat 7.0 and later, playerHonors calls honors. Parameters

doc info args

A Document Object. A PlayerInfo Object. The HonorsArgs Object to be tested.
A Boolean whose value is true if the player plug-in can honor everything in the args object. Example This example is the same as shown for the honors method of the PlayerInfo Object, but using the playerHonors JavaScript function. This works on both Acrobat 6.0 and 7.0, provided a copy of the playerHonors source code is placed into the target PDF.
function playWithRequirements( args ) { var plugins = app.media.getPlayers( 'video/avi' ) if( plugins ) { for (var plugin in plugins) { if( playerHonors( doc, plugin, args ) ) { args.players = [plugin]; return app.media.openPlayer( args ); } } } }

PlayerInfoList Object

Pl aye r I n fo L is t Obje c t
This object is equivalent to an array of PlayerInfo Objects. The individual elements (the PlayerInfo Objects) can be accessed using the usual array notation. The number of elements can be obtained from the length property. This object is returned by the app.media.getPlayers method. When a media player is created using app.media.createPlayer, the settings.players property of the PlayerArgs Object passed to the method may contain a PlayerInfoList. The created player is restricted to those in the list.
PlayerInfoList Methods select
6.0 Returns a copy of the PlayerInfoList, filtered to include only the players that match selection criteria. If no players match, an empty array is returned. Parameters object (optional) An object that contains any of the properties id, name, or version. The values of these properties may be strings or regular expressions. Specified properties are required to match. Omitted properties can match any player.
Returns PlayerInfoList Object Example 1 Use QuickTime to view the media clip.
var playerList = app.media.getPlayers().select({ id: /quicktime/i }); // QuickTime supports palindrome, so lets try it. var settings = { players: playerList, palindrome: true }; var player = app.media.openPlayer({ settings: settings });

cString

The string to be converted.

stringFromStream

6.0 This function converts a ReadStream Object to a string. Typically, this is used to examine the contents of a stream object returned as part of a response to a SOAP method. Parameters

oStream

The ReadStream Object to be converted.

Sound Object

5.0 This object represents a sound that is stored in the document. The array of all Sound objects can be obtained from the Document Object sounds property. See also Document Object methods getSound, importSound, and deleteSound.

Sound Properties name

The name associated with this Sound object. Type: String Example
console.println("Dumping all sound objects in this document."); var s = this.sounds; for (var i = 0; i < this.sounds.length; i++) console.println("Sound[" + i + "]=" + s[i].name);

Sound Methods pause

Pauses the currently playing sound. If the sound is already paused, the sound play is resumed. Parameters None Returns Nothing
Plays the sound asynchronously. Parameters None

Sound Methods

Stops the currently playing sound. Parameters None Returns Nothing

Span Object

S p a n O b je c t
6.0 This object represents a length of text and its associated properties in a rich text form field or annotation. A rich text value consists of an array of span objects representing the text and formatting.
Span objects are a copy of the rich text value of the field or annotation. To modify and reset the rich text value to update the field, use the Field Object richValue property, , or the Annotation Object property richContents, and the event Object properties richValue, richChange, and richChangeEx.
Span Properties alignment
The horizontal alignment of the text. Alignment for a line of text is determined by the first span on the line. The values of alignment are

Executes an SQL statement through the context of the Statement object. On failure, execute throws an exception.
There is no guarantee that a client can do anything on a statement if an execute has neither failed nor returned all of its data.

Statement Methods

The SQL statement to execute.
statement.execute("Select * from ClientData");
If the name of the database table or column contains spaces, they must be enclosed in escaped quotes. For example:
var execStr1 = "Select firstname, lastname, ssn from \"Employee Info\""; var execStr2 = "Select \"First Name\" from \"Client Data\""; statement.execute(execStr1); statement.execute(execStr2);
A cleaner solution is to enclose the whole SQL string with single quotes, so that table and column names can be enclosed with double quotes:
var execStr3 = 'Select "First Name","Second Name" from "Client Data" '; statement.execute(execStr3);
See getRow and nextRow for extensive examples.

getColumn

Obtains a Column Object representing the data in the specified column.
After a column is retrieved with one of these methods, future calls attempting to retrieve the same column may fail.

nColumn

The column from which to get the data. It may be a column number or a string containing the name of the column (see the ColumnInfo Object). (optional) Which of the ADBC JavaScript Types best represents the data in the column.

nDesiredType

Returns A Column Object representing the data in the specified column, or null on failure.

getColumnArray

Obtains an array of Column Objects, one for each column in the result set. A best guess is used to decide which of the ADBC JavaScript Types best represents the data in the column.
Once a column is retrieved with one of these methods, future calls attempting to retrieve the same column may fail.
Parameters None Returns An array of Column Objects, or null on failure, as well as a zero-length array.

getRow

Obtains a Row Object representing the current row. This object contains information from each column. As for getColumnArray, column data is captured in the best guess format. A call to nextRow should precede a call to getRow. Calling getRow twice, without an intervening call to nextRow, returns null for the second getRow call. Parameters None Returns A Row Object. Example 1 Every Row Object contains a property for each column in a row of data. Consider the following example:

Get dads name, an attribute.
var b = XMLData.applyXPath(myXML, "//family/dad/@name"); b.saveXML('pretty'); <?xml version="1.0" encoding="UTF-8"?> name="Bob" // assign to a variable var dadsName = b.value; // dadsName = "Bob"
Get all attributes of dad node.
var b = XMLData.applyXPath( myXML, "//family/dad/attribute::*" ); for(var i=0; i < b.length; i++) console.println(b.item(i).saveXML('pretty'))
The loop above outputs the following to the console.
<?xml version="1.0" encoding="UTF-8"?> id="m2" <?xml version="1.0" encoding="UTF-8"?> name="Bob" <?xml version="1.0" encoding="UTF-8"?> gender="M"
Extract particular information from this
console.println("For attribute 2, we have " + b.item(2).name + " = '" + b.item(2).value + "'.");
which yields an output of
For attribute 2, we have gender = 'M'.

Get dads second child.

var c = XMLData.applyXPath(myXML, "//family/dad/child[position()=2]"); c.saveXML('pretty') <?xml version="1.0" encoding="UTF-8"?> <child> m5 </child>
This is the id of dads second child. The examples below get the family data on this child. The following returns a string.
// calculate the value of dadsName using XPath methods. var dadsName = XMLData.applyXPath(myXML, "string(//family/dad/@name)")
// dadsName is assigned a value of "Bob" with this one line.
Get the family information on dads second child. The following line assigns c = "m5". The return value of the call to applyXPath is a string, and he function normalize-space converts its argument to a string and removes any surrounding spaces.
var c = XMLData.applyXPath(myXML, "normalize-space(//family/dad/child[2])"); var d = "//*[@id = \'" + c + "\']"; // Note: d= "//*[@id = 'm5']" XMLData.applyXPath(myXML, d ).saveXML('pretty'); // show what we have <son id="m5" name="Jim" gender="M"> <parent> m2 </parent> <personal> <income>35000</income> </personal> </son>
Now display information about the sixth child node of the family root. The XPath functions name and concat are used.
var e = XMLData.applyXPath(myXML, "concat(name(//family/child::*[position()=6]), '=', //family/child::*[position()=6]/@name)" ); console.println(e); // the output is "daughter=Megan"