Fillable PDF Forms

Introduction

DocOrigin supports the creation of PDF documents that contain Acroform fields to capture input from the user.

Compared to HTML, fillable PDF forms are limited. The big difference is that with HTML you can have an ever-lengthening page, allowing for much greater dynamism in a fillable HTML form while it is being viewed in the browser. With PDF forms, all of the dynamic instantiations of panes and pagination occurs within DocOrigin Merge -- once Merge produces the PDF, that PDF will be constrained to having only the panes that it was generated with. No panes can be added, deleted or even hidden while in your PDF Reader technology. Fields will not grow in width or height, though Adobe Reader does provide scrolling for multi-line input fields. All objects remain the same size -- it's a very static layout.

Still, it is quite useful to have a PDF in which a user can enter data, and then possibly print it out, or submit it to an URL that you have provided in your form design, such that you can collect the information and process it as befits your needs. It's possible that as part of that processing you will update databases, invoke other applications, and even invoke DocOrigin Merge on your web server with the same or a different form with captured and augmented data.

Supported input types: Text fields (single line and multi-line), checkboxes, radio buttons, dropdown choice lists (i.e. one line tall, with a drop list to show the choices), hidden, password, and push/submit buttons.

Unsupported input types: File, Date, Time, Email Address, URL Address, Number, Telephone Number, and Signature. Mostly those are HTML5 field types so their non-support in PDF is not surprising.

Input attributes:

A field may be marked as "readonly" and as such the value provided to it when Merge generated the form cannot be changed by the user.

The "required" option is also supported in PDF forms. When a submit is done, fields marked as required will be checked for content and a diagnostic issued if there is none. Any specification of a custom message will be ignored.

Tooltips can be specified; they will be displayed when the user hovers over the relevant field.

Hidden field: Do note the difference between an input field type of hidden versus a design object being marked as invisible. In the latter case, the object won't even be represented in the PDF. In the former case, the field is in the PDF but hidden from the user. You could access it via JavaScript.

Password field: Characters typed into a password field are displayed as asterisks, though the correct values are submitted. NOTE: If a password field is left empty then that field will not be submitted at all.

Responding to User Inputs

While you can't, with any sort of reasonable effort, change the layout of the PDF once it is displayed in the Reader you can still react to the entries that your user is providing. For the most part that means supplying or altering data that is in the form. And of course, you can cause the submission of the collected data to an URL of your choice.

If all you want to do is collect the data as entered and submit it, then that can all be done declaratively with the DocOrigin Design tool. No further 'in the Reader' effort is required.

If you wish to manipulate the data while 'in the Reader' this can be done using JavaScript. Note that this is not DocOrigin JavaScript, complete with all of its amazing extensions, but rather the JavaScript supported by the Reader. A good reference for this is: JavaScript™ for Acrobat® API Reference. That is a long and sometimes challenging read; you likely have more simple goals in mind. The following tries to grease those wheels, but you can most certainly fall back to that reference manual.

For a developer, a useful resource is always some code to look over. DocOrigin ships a critical piece of JavaScript for use in the Reader. It is called Default-DOPDFScript.js and is delivered in the .../DO/Bin folder. Note that it is .js and not .wjs. As usual, you can override that file by supplying your own DOPDFScript.js (no Default- prefix) in the .../User/Overrides folder. The important thing about this file is that it is included verbatim in every DocOrigin produced fillable PDF document. It is the thread that starts the ball rolling in terms of getting your own JavaScript code operating inside the Reader. And it happens to show some JavaScript code that may be of interest to a developer.

That's nice, but how do you get your own JavaScript code into the PDF; you certainly are not allowed to edit a file that resides in .../DO/Bin. You put your JavaScript in the "PDF Input Event" of the form object, via DocOrigin Design's Format-Form Properties menu item. You might well specify a single: #include "$$F/MyScript.js" line in that location, and then edit the referenced external file. That is often convenient, especially during development. DocOrigin Merge will append whatever you define in the PDF Input Event (and what it #includes) into the generated PDF document. Your code will immediately follow the code you see in DOPDFScript.js. There... now you can get your own JavaScript into the PDF.

But what can you do using JavaScript? Lots, if you read that whole reference manual. But more likely you simply want read/write access to the values of the fields on the form. This is not overly difficult in a PDF since there won't be any dynamic additions/removals of panes. What you start out with is what you have. [Yes, you, having thoroughly digested the entire reference manual, and really being in the wrong business, could manage to alter the form layout and content while in the Reader, but that is not the goal here.]

Getting a field's value

Consider the following:

 var fName = "MyInterestingField";
 var f = DO.doc.getField(fName);
 var v = f.value;
 //console.println("Field " + fName + " has value " + v);
 f.value = "I clobbered it's value";

Well, that's pretty easy. DO.doc is literal. Its value is defined by DOPDFScript.js. Often you could use this instead. But you can be assured that DO.doc always refers to the DocOrigin generated document in the PDF, no matter what context you find yourself in.

Now your only problem is knowing what the names of the fields are. The code in DOPDFScript.js shows how you can enumerate the fields; then you could examine their ".name" attribute. Generally, the names are of the style:

Page1.Pane1.GroupName.FieldName

Another great way to know the names of the fields in your PDF document is to use, during development, a submit button that submits the data to "http://docorigin.com/echo.php". All it does is echo out the names and values of the fields in the form. The echo.php file is also provided, as an unsupported sample, in .../DO/Samples/Web. You could alter it (or not) and deploy it onto your own web server. We really have no interest in seeing the data that your forms submit! We certainly don't collect it.

We can't emphasize enough just how instructive it is to see the names of the fields as they are / would be submitted. Highly informative. In there, you would see some special $DO_xxxxx fields that provide some context, and also how radio button group values are submitted.

Radio Buttons

First off, for fillable PDF forms, you MUST enclose your radio button sets in a DocOrigin group construct. Of course, all of the radio buttons in the set must have the same name. It may be a fine idea to give that enclosing group that very same name too. The group construct should have no other objects within it; just the same-named radio button fields.

Unlike HTML, PDF radio button sets must be contained within a single pane.

Every radio button input field must be given a "Choice:" value in the field's Input dialog, or via DocOrigin Merge script, before the PDF is actually output. Using the classic credit card example, these choices could be: American Express, Visa, or Mastercard. They define the value to be associated (and submitted!) as the value of the overall radio button set.

Let's say that we have a radio button set in which all of the radio button fields are named: CreditCard, and they are grouped in a group named, for lack of imagination, CreditCard. The leaf (trailing) node of the field that is submitted would be: $DO_CreditCard. It is a specially manufactured field that contains the current value for the radio button set. If there were three individual radio buttons (PDF-ese would call them widgets), they too would have values submitted, named: CreditCard#1, CreditCard#2, and CreditCard#3. Their values would be only either '0' or '1', indicating whether that particular widget was checked or not. This is accomplished through very special DocOrigin Merge fillable PDF construction. It is useful to have that in the submitted data in order to generically produce an XML file that can be reprocessed by DocOrigin Merge. Of course, the overall radio button set value, as submitted in $DO_CreditCard is quite invaluable too. It, for example, might contain the value Visa.

Set the radio button value

You do not set the value of a radio button set directly, using its .value property. Instead, you check one of the buttons within the set. This can be done with the Reader-provided functions:

 var f = DO.doc.getField("$DO_MyRBSet"); // of course the name would be a hierarchical name
 f.checkThisBox(2);                      // 0-based, so check the 3rd radio button

For what it is worth, you can determine whether any individual button is set by using the f.isBoxChecked( i ) function. Since the .value property of the radio button group object always reflects the button that is checked, using the isBoxChecked() function is pretty exotic.

Push/Submit Buttons

There is no difference between Pushbutton and Submit Button. You can provide an URL target in either case. Somewhat more interesting is that you can provide a "Viewer attribute" such as onClick="MyFunction();". In fact, this can be done on any field. When the user clicks on the field (actually when they 'mouse up' on the field) the on-click code will be called.

You can define your functions in your own JavaScript which you know how to get into the PDF. Also, there are a number of actions beyond 'onClick' but that one is the most common one.

Special Functions

Initialize(): If you look at DOPDFScript.js you can see that, as soon as the PDF is loaded, it will call a function named Initialize if you have provided one. Do note the uppercase I. It is case-sensitive. Naturally, that is a great place to do, well, initializations.

PreSubmit(): If you attempt to do a form submission, via DO.submitForm -- which is the standard way -- then it will call a function named PreSubmit, if you have provided one. If that function returns false, then the submit operation will not be done.

Binding Script

Another common case is to bind script to a particular event, e.g. field value change.

This can be implemented using the setAction() method. For instance:

this.getField("FieldName").setAction("Keystroke", "some JS code");