Thom Parker December 1, 2009
Was this tutorial useful to you?
By the way, when you see the capitalized word "Reader" in this article it means Adobe Reader.
Adobe Reader is a much smaller and more restrictive tool than Acrobat Professional. Reader is free and intended for viewing PDF files, not creating and modifying PDF files like Acrobat. So in general, any operation that’s related to PDF creation and modification is not allowed. To be more specific, Reader coding restrictions can be placed in 4 categories:
Figure 1 – Each box in the Rights Bar indicates a specific usage restriction
Let’s take a closer look at how these restrictions work by examining the Rights Bars for some common scripting functions. The Rights Bar shown in Figure 2 is for the most common function used in any PDF script. The Doc.getField() function is used the acquire a Field Object.
Figure 2 – No usage restrictions
Now let’s look at a heavily restricted operation, the Doc.insertPages() function (Figure 3).
Figure 3 – Can only be used under special circumstances
This function was added to Acrobat in version 5. Knowing the version an operation was added in is very important. It is generally a bad idea to use operations added in the most recent versions of Acrobat, because many Reader users will still be at least one or two versions behind. It is also common for Adobe to add new features (function inputs) to an existing operation. This information won’t be listed in the Rights Bar, so be sure to read all the documentation for the features you’ll be using.
The version number listed here is old, so if it wasn’t for the other restrictions, we’d be OK using this function. However, the fourth and last column has an X in it. This is the Reader column and the X tells us this operation does not exist in Reader. Further, column three has a red S, indicating that the function also requires privilege, meaning for the most part that it cannot be used in a PDF script at all. This function can only be used in an Acrobat automation script. It’s not even close to suitable for a script in a document viewed in Reader.
The Field.setItems() function (Figure 4) is used to set the items in a list. This seems like a very standard form operation. Acrobat considers anything that changes a field property to be a document modification, which requires a special right to be performed in Reader. The D in column two indicates this function modifies the document. Nearly all operations with a D in this box will also require a Reader Right. In this case, since the function affects a form field, it requires Form Rights. Other operations that require this same Right include modifying the fill color, border style, field font, and similar operations.
Figure 4 – Any operation that modifies the document usually requires Form Rights
Figure 5 – One feature of the print requires Privilege
This does not mean the print() function cannot be used in a document script. It does mean that some care is needed when using this function, and a little further reading in the documentation reveals this note (Figure 6).
Figure 6– Typical security note for any operation with a red S in column three
Notes like this are standard for any operation with a red S in the Rights Bar. In this case, the note indicates that only non-interactive printing is Privileged, meaning that Acrobat does not allow a document script to print silently. In the Acrobat security model, the user must approve all operations that touch resources outside of Acrobat/Reader. This type of restriction on the print() function and any other similar operation is expected.
The save function, doc.saveAS() (Figure 7), has two restrictions as shown by the entries in the last two boxes of the Rights Bar. The S in the last box, the Reader box, indicates this function can be used in Adobe Reader, but only if the PDF is enabled with Form Save Rights. The security note for the red S in column three indicates the entire function is privileged. The result of these restrictions is that the save function is not suitable for generally distributed documents; but it is useful for certain types of forms that will be viewed in Reader. To understand this, both of these restrictions require more explanation.
Figure 7 – Requires both Reader Rights and Privilege
There are a number of operations available in Adobe Reader that are blocked unless the document has been enabled with a Right specific for that operation. When Adobe first added these enabling rights, the only way they could be applied to a PDF was with a special Adobe Rights Server. Few customers could afford this server, so the general attitude was if an operation required Rights Enabling, then it might as well not exist because you couldn’t use it.
In Acrobat 7, commenting rights (the ability to apply markup comments to a PDF) were added to Acrobat Professional. Then in version 8, Form Save (the ability to save a filled in form), Form Rights (performing advanced field manipulation), and Digital Signing Rights were added to Acrobat Professional. These Reader Enabling Rights opened up a whole new world of scripting functionality that could be applied to a PDF viewed in Reader. However, there are still several Rights that can only be applied by what is now called the LiveCycle ES Rights Server. These include File Embedding, Spawning Page Templates, SOAP operations, as well as a few others.
Reader Enabling Rights are like a digital signature. They mark the whole document and any changes made to the PDF after the Rights are applied will invalidate them. So this is the very last thing that should be done to a PDF using these features.
The second method is to digitally certify the PDF, then install the digital signature on the user’s system so the signed file can be verified by Reader. When the certification is verified, all scripts in the PDF become privileged. The downside to this methodology is that it’s possible for older versions of Reader and for Acrobat users to make changes to the PDF that invalidates the certification, thus destroying the privileged operation. If both Reader Rights and Digital Certification are applied to a PDF, the certification must be done last.
Both of these methodologies require changes to be made to the user’s system. This means that privileged operations are not suitable for generally distributed documents. They can only be used within a more intimate environment. For example, the trusted function methodology is perfect for use within a single office or company. The digital certification methodology is often used with customer/vendor forms since trading digital signatures is more controllable and practical than installing and maintaining scripts at remote locations.
Adobe does not recommend this, but it’s very useful to have Adobe Reader on the same system as Acrobat so you can develop and test on the same system. In fact, both Reader and Acrobat can be open at the same time, so you can modify a PDF in Acrobat and then immediately test it in Reader. To do this, you’ll need to add a shortcut (or link) to Reader on your desktop. The shortcut should use a line like this one to reference the Reader program:
"C:\Program Files\Adobe\Reader 8.0\Reader\AcroRd32.exe" /n
The "/n" option specifies a new window. Normally, if Acrobat or Reader is already open, then any reference to either executable will defer to the already open program. The "/n" option overrides this behavior.
Installing the console window
The most useful test and debug tool in Acrobat is the Console Window. The console is not a native feature in Reader, but Adobe added it as an optional feature to Reader 7 and later. Three things need to be done to install and activate the console window in Reader.
It’s best to start out by opening your non-Reader Enabled PDF in Reader to see how things work. This will help reduce development time and save testing the operations that require Reader Enabling until everything else is tested. You can also save time by using the console window to test out code before entering it into scripts in the PDF.
If the console reports an error, it’s more than likely it will report a security error, regardless of the actual error (Figure 8). In this example, the Doc.addField() function requires Form Rights and the error will stop being reported when the PDF is Rights Enabled.
Figure 8 – Most of the time Reader will report a security violation regardless of the actual error
It is also important to be version aware. Documents that are Reader enabled will work best when viewed in the same version of Reader in which they were enabled with Acrobat because Reader Rights tends to be a shifting landscape. For example, a document that was Reader Enabled in Acrobat 8 has a script that changes the fill color of a form field under some special circumstance. When viewed in Reader 8, the form can be filled out, saved, then reopened and modified without a problem. When the same PDF is viewed in Reader 9, it can be filled and saved without a problem until the code that changes the field fill color is activated. If this happens, the Rights Enabling will be invalidated the next time the PDF is opened.
This situation is a quirk of the particular versions involved and the issue has changed with minor version updates from Adobe. Reader Rights, as well as security issues, are shifting sands. So always test the PDF on the target platforms, and try not to use too many operations that require Reader Rights.
Happy Reader Scripting!!