[This blog post appeared first on my professional site at KHKonsulting.com]

A New Version of Acrobat

Have you noticed that it’s been more than two years since the release of Adobe Acrobat 9? Usually, Adobe releases a new version every 18 to 24 months, so a new version has been overdue. Today they let the cat out of the bag, and announced Acrobat X. There is already a lot of information available about what it is, and to some extend also how it is different from previous releases.

Take a look at the press release to get a quick overview of what’s new, or browse over two Adobe TV and watch the Acrobat X Tips & Tricks episodes. There is a lot of information available to give you a pretty good idea about what’s new and different.

User Interface

If you’ve attended one of my training seminars about Acrobat, you know that one of my pet peeves has always been that Adobe added to the UI clutter with every new release of Acrobat. Yes, every now and then they tried to clean it up, but at the end, it just caused more and more confusion among both novice, but also experienced users.

This time around, they took a completely new approach and ripped out the old menu and toolbar system and replaced it with something completely new. I am still trying to wrap my head around where things are now located, but in general, the new layout is a good idea. It will be much easier for the novice user to explore the UI and find new features that they might want to use, but for users who’ve worked with Acrobat since the early days of the product (in my case since Acrobat 3), it will take a while until we find all the tools that we’ve known by heart. But in the long run, I think it’s a good move, and I am more than willing to go through the learning process to get to know the new UI.

Plug-Ins

Every time Acrobat changed it’s UI in the past, there were major ripple effects through the plug-in community – things just did not work anymore, or not quite right, and we plug-in developers had some work to do to modify our plug-ins so that users could rely on these 3rd party components again.

If you have not yet tested your own plug-ins on an Acrobat X pre-release, don’t waste any time. Chances are that your code needs to be modified to work seamlessly with Acrobat X. If you need help with that, get in touch with me, I am a seasoned plug-in developer and I can certainly assist you with those efforts.

Favorite Feature

I don’t have a favorite new feature, but I have two favorite updated features:

Number one is what Adobe has done with Portfolios. In my opinion, Portfolios were one of the most underused features in Acrobat 9, and I hope that the updates to the Portfolio system will help to give that feature the necessary exposure so that we see more and more of these compound documents.

My number two updated feature is the much improved export function to other file formats. Whenever I had to create a MS Word document out of a PDF file in the past, it was always a hit-or-miss job – some documents worked reasonably well, others didn’t work at all. But regardless of how well it worked, there was always some editing necessary after the export to make the Word file look like the original PDF document. With the new export in Acrobat X, I get Word documents that look exactly like the PDF file. Great job, Adobe!

I’ve written about VBA and Acrobat JavaScript before, and I’ve also mentioned that you can combine VBA and JavaScript to access PDF form fields, but I still owe a sample for that. I had to answer another question today about how to exactly do that, so I whipped up a quick sample program that demonstrates the use of the JavaScript Object (JSO) to read and write AcroForm fields.

We start the same way as in my old VBA sample to create a VBA program that references the Acrobat TLB and to add a button to a document. When we now use the following script as the button handler, we can work with form fields:

Private Sub CommandButton1_Click()
    Dim AcroApp As Acrobat.CAcroApp
    Dim theForm As Acrobat.CAcroPDDoc
    Dim jso As Object
    Dim text1, text2 As String
    
    Set AcroApp = CreateObject("AcroExch.App")
    Set theForm = CreateObject("AcroExch.PDDoc")
    theForm.Open ("C:\temp\sampleForm.pdf")
    Set jso = theForm.GetJSObject
    
    ' get the information from the form fields Text1 and Text2
    text1 = jso.getField("Text1").Value
    text2 = jso.getField("Text2").Value
    
    MsgBox "Values read from PDF: " & text1 & " " & text2

    ' set a text field
    Dim field2 As Object
    Set field2 = jso.getField("Text2")
    
    field2.Value = 13   ' assign the number 13 to the fields value
    
    ' get the information from the form fields Text1 and Text2
    text1 = jso.getField("Text1").Value
    text2 = jso.getField("Text2").Value
    
    MsgBox "Values read from PDF: " & text1 & " " & text2

    theForm.Close
     
    AcroApp.Exit
    Set AcroApp = Nothing
    Set theForm = Nothing
     
    MsgBox "Done"
End Sub

This program requires a PDF file with text fields called “Text1″ and “Text2″ to be stored as C:\temp\sampleForm.pdf. With the explanation in the previous two blog posts, it should not be hard to understand what’s going on here. The only new command introduced is the getField() function, which returns a form field. The form field object has a property “value” which contains the actual value that’s assigned to the field. Give it a try and let me know how it works for you. The updated form field is not saved (because the document does not get saved) – I’ll leave that up to the reader to figure out.

Also, this program will not work with XFA forms (the ones you create in Designer). For those, you need to use the XFA DOM to access the form data. For anybody interested in XFA forms, the LifeCycle Designer ES Scripting Reference is a must read.

Have you ever tried to fill a PDF form in Adobe Reader and to then save that filed document to your hard disk? Did it work? Chances are that it did not.

Have you ever thought about why the Adobe Reader is called “Reader”? The answer is pretty obvious, it’s because it is only reading and displaying (and printing) PDF files – that is, it is not writing them. That also includes that it will not save a modified document. You would need the “Adobe Writer” – or “Adobe Acrobat” as it is called for that.

But regardless of the name, we can “trick” the Reader into writing a filled form to the disk. OK, it’s not really a trick, Adobe did implement this feature, so it’s official, and we are not hacking or cracking anything.

Adobe has a server based solution that does allow you to create PDF files that are “reader enabled”: Adobe LiveCycle Reader Extensions ES
That technology allows you to “Fill in, sign, comment on, or save Adobe PDF files using only Adobe Reader”. Sounds like the perfect solution. Let me tell you a little secret: Whenever you hear the terms “Adobe” and “Server” in the same sentence, it usually means expensive…

Here is another secret – not really, it’s documented in a lot of places, but Acrobat users often don’t know about it: You can use Adobe Acrobat to “reader enable” PDF files as well. However, when you agreed to the EULA during the installation of Acrobat, you also agreed to using this technology only for a form with a maximum of 500 copies. The reason for that is of course, that Adobe still wants to sell the server based solution for document workflows that involve more copies.

So, let’s take a look at the EULA and find out exactly what we agreed to:

“15.12.3 For any unique Extended Document, you may only either (a) Deploy such Extended Document to an unlimited number of unique recipients but shall not extract information from more than five hundred (500) unique instances of such Extended Document or any hardcopy representation of such Extended Document containing filled form fields; or (b) Deploy such Extended Document to no more than five hundred (500) unique recipients without limits on the number of times you may extract information from such Extended Document returned to you filled-in by such Recipients. Notwithstanding anything herein to the contrary, obtaining additional licenses to use Acrobat Pro or Acrobat Pro Extended shall not increase the foregoing limits (that is, the foregoing limits are the aggregate total limits regardless of how many additional licenses to use Acrobat Pro or Acrobat Pro Extended you may have obtained). “

You may want to review that with your lawyer, I’m just an engineer, and in no position to give legal advice. I’ll however let you know what my interpretation of that section is: We have two options, we can either distribute our enabled form to an unlimited number of users, but we can only process a maximum of 500 unique responses. So, if we distribute our form to 1000 recipients, and we get 500 copies back, we are good. If we receive 501 replies, we can process the first 500, but the last one we cannot even look at. It also does not matter if we receive the filled out forms via a printed sheet of paper, or electronically. The second option is a bit more complicated, and you really should talk to your lawyer about that. To me it seems that you can distribute 500 copies of your form to 500 unique recipients, and they can then submit that form as often as they want. This could e.g. be a form that needs to be submitted once a week. Every one of your (up to 500) users/customers/clients has a copy of that form, and then once a week they fill in new data and submit the form.

Now we know what we can do with these forms, but we still don’t know how to use Acrobat for that. Let me show you a few screen shots.

Let’s assume you have a PDF form that you want to distribute, open that file in Acrobat and select “Forms>Distribute Form”:

This will bring up the dialog that we need to work with for the next few steps:

As you can see, I’ve selected to manually collect the responses in my email. That’s the most straight forward option and does not require any other configuration. The information presented below the selection does give you a pretty good idea about what it is. For now, let’s stick with the email option, but please, play around with the other options and let me know if you run into problems.

In the next step we specify the target location on our local hard disk for the protected (and now reader-enabled) copy of our file:

Now we need to add some information about us, the author:

We get one more chance to revise our decision about the delivery method, so if you want to take a different approach, and use Acrobat.com to collect the returned forms, here is your last chance. I will stick with the email option:

Once we click on the “Finish” button, the form will be prepared and saved, and Acrobat will display the Tracker interface. That dialog can also be opened via the “Forms>Track Forms” menu item (see the menu screen shot from above). I will talk more about that in a future post.

All you have to do now is to distribute your form. In a future post I will talk about how to process the returned data.

If allowing your users to locally save a form, you are done. They now can partially fill a form, save it, open it at a later time and continue with the form.

OK, let’s just forget about that old joke and concentrate on how to combine all three into something that is quite useful.

As I’ve described in one of my previous posting, it is quite easy to automate Acrobat from VB or VBA. So how does JavaScript fit into this picture? As you may know, Acrobat comes with a very powerful JavaScript engine that provides access to a lot of functionality – more functions actually than what you have access to from your VB program. So, if you want to access some of these features, but you are stuck with VB, how can you do that?

Adobe provides a VB/JavaScript bridge with Acrobat – the JSObject, and the Acrobat SDK describes how to use that feature.

There is quite a bit of good information in the documentation. When you access the online documentation, expand the tree to “Acrobat Interapplication Communication > Developing Applications Using Interapplication Communication > Using OLE > Using the JSObject interface”.

JavaScript

In this example, I want to illustrate how you can create a folder level JavaScript function, instantiate the JSObject, and then call the custom function and display the result in VB. My plan was to use the JavaScript code from my last posting, but I found one small problem in the way I wrote the code (it works fine as a standalone JavaScript program, but we cannot use it in the VB context), so here is it’s replacement:

function CountBookmarks(bkm, nLevel)
{
    var count = 0;
    if (bkm.children != null)
    {
        count = bkm.children.length;
        for (var i = 0; i < bkm.children.length; i++)
        {
             count += CountBookmarks(bkm.children[i], nLevel + 1);
        }
    }

    return count;
}

function CountAllBookmarks()
{
    console.clear(); console.show();
    var n = CountBookmarks(this.bookmarkRoot, 0);
    console.println("Number of bookmarks found: " + n);

    return n;
}

// add the menu item
app.addMenuItem({
     cName: "countBookmarks",
     cUser: "Count Bookmarks",
     cParent: "Document",
     cExec: "CountAllBookmarks();",
     cEnable: "event.rc = (event.target != null);"
});

Save this JavaScript program as a folder level JavaScript file and make sure that it works.

So, why can’t we just implement the whole algorithm with the JSObject? The problem is with how VB handles objects that are actually JavaScript objects – in this case the root bookmark object. I cannot figure out how to access it’s “children” property through the JSObject. That’s the reason why I’m “cheating” by calling our custom JavaScript function – being able to do that is pretty cool IMHO.

The VB Part

We start out just like with any other VB program, by declaring some objects, initializing them and then it gets interesting…

Here is some sample code that shows how to initialize the JSObject, and how to call our own JavaScript function.

Create a button on an Excel spreadsheet again, and put the following code into the button handler callback (just like before).

Dim gApp As Acrobat.CAcroApp
Dim gPDDoc As Acrobat.CAcroPDDoc
Dim jso As Object

Sub Button1_Click()
    Set gApp = CreateObject("AcroExch.App")
    Set gPDDoc = CreateObject("AcroExch.PDDoc")
    If gPDDoc.Open("c:\temp\test.pdf") Then
        Set jso = gPDDoc.GetJSObject
        MsgBox (jso.CountAllBookmarks())
    End If
End Sub

Now just make sure that you have a file c:\temp\test.pdf that has some bookmarks in it.

Let’s assume you have a PDF document, and you want to know how many bookmarks you have in that document, how would you approach that?

The JavaScript API has methods to traverse the bookmark tree. Here is a short program that – once installed in Acrobat’s JavaScript folder – will add a menu item “Count Bookmarks” to the “Document” menu, and when executed will print the number of bookmarks encountered in the JavaScript console.

function CountBookmarks(bkm, nLevel)
{
    var count = 0;
    if (bkm.children != null)
    {
        count = bkm.children.length;
        for (var i = 0; i < bkm.children.length; i++)
        {
             count += CountBookmarks(bkm.children[i], nLevel + 1);
        }
    }

    return count;
}

function DoIt()
{
    console.clear(); console.show();
    var n = CountBookmarks(this.bookmarkRoot, 0);
    console.println("Number of bookmarks found: " + n);
}

// add the menu item
app.addMenuItem({
     cName: "countBookmarks",
     cUser: "Count Bookmarks",
     cParent: "Document",
     cExec: "DoIt();",
     cEnable: "event.rc = (event.target != null);"
});

Save this program in a file in e.g. C:\Program Files\Adobe\Acrobat 9.0\Acrobat\Javascripts (for Acrobat 9) and restart Acrobat. You should now find a new menu item in the Document menu. Load a file with bookmarks in it, and execute the menu item.

I have not implemented the privileged execution context that is required to make this work in all instances, so you have to go into your JavaScript preferences in Acrobat and check the setting for “Enable menu items JavaScript execution privileges”: