PDF In-Depth

Doc discovery more difficult in Acrobat 5.0.5

January 02, 2001

Advertisement
Advertisement
 

Until now, one of the most useful of the many new Acrobat JavaScript properties to be introduced with version 5.0 was the activeDocs property on the App object. I say "until now" because with the 5.0.5 upgrade to Acrobat, the activeDocs property has effectively been crippled, for reasons unknown.

The activeDocs property is an array containing Doc object references for every open PDF document (or at least, that's the way it *used* to work). By consulting app.activeDocs, you could determine at runtime how many docs are open and get the Doc handle for any one of them so that you could, say, inspect the filesize or other characteristics of a remote doc, or bring a given doc to the front with bringToFront(), etc. Remote manipulation of documents with JavaScript was difficult prior to Acrobat 5.0, because the only way for one document to find another document's Doc object reference was for the second doc to "publish" its handle to a global variable, where the first doc could find it. This took coordination between the two documents (because they both needed to know in advance the name of the global variable) and was therefore clumsy. Also, there was no way for the global list of doc handles to be kept valid at all times, because a document could close without removing its reference from the global list.

The activeDocs property solved these problems. In effect, app.activeDocs became the "global variable" to which all Doc references were (automatically) published. And the list was kept up-to-date by Acrobat. Whenever a doc closed, its reference was removed from activeDocs automatically.

With the upgrade to 5.0.5, activeDocs has been crippled beyond usability. If you do read the ReadMe notes for Acrobat 5.05, you will come across an interesting change notice:

"JavaScript Updates in Acrobat 5.0.5"

"A new boolean property, 'disclosed' is available for the Doc object, and its default value is 'false.' Even if the API call app.openDoc is successful opening the requested document, it returns value 'false' to the caller unless the opened document sets Doc.disclosed to 'true' as part of a Doc-level script. If Doc.disclosed is 'true,' Doc.openDoc returns the Doc Object of the document opened by this method."

"app.activeDocs only includes in the returned array the Doc Object for each active document open in the Viewer that has set Doc.disclosed to 'true' at the time of app.activeDocs invocation.[463695]"

Read that last part again. What it says is that by default, activeDocs contains nothing. The only time it contains anything is when a document has taken pains to publish itself via the "disclosed" mechanism. That is to say, in order for a document to be listed in activeDocs, the document has to contain a Doc-level script that says "this.disclosed = true". If that line of code doesn't exist somewhere in a document, the document will never be listed in app.activeDocs. Therefore, by default, you can never discover any open documents. You can only discover them in the non-default case where someone (you) has taken special efforts to set a visibility tag on each open doc.

This puts us right back to the situation we were in pre-5.0. In essence, the JavaScript programmer no longer has an easy way to enumerate open docs.

The impact of the 5.05 change on app.openDoc() is also worth considering. The app.openDoc() method opens a PDF doc if you supply a device-independent doc path. Before 5.0.5, this method returned a Doc object reference (if the doc opened successfully), or else threw an exception (if your path argument was no good). Now it simply returns false, unless the document you're opening contains the magic line of script ("this.disclosed = true"). But it will still throw an exception (rather than return an error value) if the path argument isn't usable.

The bottom line for developers is that when it comes to remote document manipulation, we're back in the same predicament we were in before Acrobat 5.0. Documents are (once again) "undiscoverable" by default. There is no way to enumerate open docs at runtime, and even if you know the path to a given doc, you can't obtain its Doc reference simply by opening it with docOpen().

Needless to say, this makes it difficult to create PDF-based "interface" applications designed to operate on other docs (such as a test-grader doc that can operate on PDF quizzes, or a form-designer doc that can remotely create and manipulate fields in other docs). Perhaps Adobe expects that all of our doc-manipulation needs can be met with batch actions or that all of our interdocument information-sharing needs can be met with ADBC.

It would be interesting to know exactly what Adobe had in mind when the decision was made to cripple activeDocs in 5.0.5.

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Quick PDF Library

Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

Download free demo

Back to the past, 15 years ago! Open Publish 2002

Looking back to 2002, it's amazing how much of the prediction became a reality. Take a read and see what you think!

September 14, 2017
Platinum Sponsor





Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.

Features

Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.