If you intend to create forms for your website, whether authored in HTML or in PDF,
you’re going to have to learn some JavaScript. Not a lot, but some. If you’re new to the
language, you’ll need to read up.
For a good hit-the-ground-running introduction to JavaScript, I recommend Peachpit
Press’s Visual Quickstart Guide on JavaScript by Negrino and Smith, ISBN 0-201-69648-7. At
$17.95 list, it’s a bargain. When you graduate from that book to needing a for-real
heavy-duty text covering the language in some depth, you have no option (in my opinion) but
to go straight to David Flanagan’s JAVASCRIPT: THE DEFINITIVE GUIDE, an O’Reilly book (with
a rhino on the cover).
PDF JavaScript vs. Browser JavaScript
Traditional JavaScript is browser-executed. It runs inside the browser and gives you
access to a great deal of browser functionality via methods that access the Document Object
Model components. None of this, however, has anything to do with PDF-based JavaScript.
While it’s true that Adobe has implemented core JavaScript per the 1.2 specification
inside the PDF spec, that does not mean you can access browser functions or HTML document
objects from within PDF-based JavaScript. The JavaScript you put in a PDF form or document
gets executed inside Acrobat or Acrobat Reader. The browser knows nothing about this.
Indeed, you can’t reach the browser from within a PDF file. They live in separate
worlds.
Adobe has not only implemented core 1.2 JavaScript but has extended it to cover new
objects, with methods available only to PDF files. These objects and methods are covered in
Adobe’s documentation. Look for a document called AcroJS.pdf on Adobe’s web site or
on your Acrobat CD. This docfile describes in detail how PDF-based JavaScript is
implemented. Early in the document it states:
Acrobat Forms defines an object model on top of JavaScript 1.2. These objects are only
defined within the Adobe Acrobat realm and are specific to Acrobat Forms. They basically
mirror the Acrobat Forms components and give the forms developer a way to access these
components programmatically in order to query and change their properties. In addition to
defining forms specific objects, there are additional generic objects that allows the
developer to access the underlying document and perform certain actions on it.
An example of an additional object is the app object, which has methods like
beep and alert. (These methods issue a system beep and an alert dialog,
respectively.) The app object also has properties. One property it has is the
fullscreen attribute, which is a Boolean value. If you call
app.fullscreen = true
from inside your PDF-based JavaScript, you will force the user’s viewing application
(i.e., Acrobat Reader) into fullscreen mode, making menus disappear and generally making it
seem as if your form has taken over the user’s machine. (This may be disconcerting to the
user, of course!) If you set this value to False, you will make the viewing app go back to
its default viewing mode.
How to Attach JavaScript to a Widget
In HTML, you insert JS code into your main HTML document, usually in various places
throughout the document, and the document ends up being quite long and almost impossible for
a normal human being to read and understand.
In PDF, you attach JS snippets to individual widgets visually, with the mouse,using
Acrobat’s form tool. Choose the form tool, then doubleclick on whichever field you want to
attach JS to. Click the Actions tab and decide whether to attach your code to a mouse
action, or make it a Validate script, or a Calculate script, or a Format script. (These
latter options will mainly be available in Text fields.) For example, select a mouse action,
hit the Add button, and choose JavaScript from the pulldown menu. Then type or paste your
script.
An Actual JavaScript Example
Take a look at the following code, which shows how to change the Fill Color of all of a
PDF form’s fields at runtime:
var rgb = new Array('RGB',.5,.5,.5);
for(var i =0;i<this.numfields; i++)
= this.getNthFieldName(i);
= this.getField(s);
f.fillColor=rgb;}
We will walk through this code step by step, in great detail, later.