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.

Every now and then I come across the question “What is the best way to learn scripting for Adobe Acrobat? Are there any books or other resources averrable?”. After doing some research, I think I finally found the best resource for beginners and for seasoned Acrobat JavaScript programmers that need a quick tip or a recipe to copy&paste into a project:

PDFScripting.com

The site offers content for both paying members and the general public. If you are new to scripting, and you don’t want to spend the money for a membership (yet), take a look at the free content at http://www.pdfscripting.com/public/department40.cfm – it walks you through creating your first AcroForm script, but also offers a number of videos that explain more complicated concepts. For the really good stuff however, you have to pay.

Ever wondered how to hook up a PDF form with an Excel spread sheet? Wonder no more! The article series “Acrobat, PDF and Excel Spreadsheets” teaches you more than you ever wanted to know about that subject.

You may remember my post about dynamic stamps in Acrobat. The PDFScripting.com site has a lot more information about dynamic forms and provides a number of very interesting samples (video link).

There is a ton more information available for both AcroForm and LiveCycle Designer scripting. This information comes in form of articles, videos, a copy&paste script library and downloadable sample files that illustrate a subject.

To get familiar with the web site, Thom Parker has recorded a video tour that helps to navigate the site, but also gives a pretty good overview about what’s available both for free and for paying members at “Take a tour of the PDFScripting.com website!” (video link).

So, no need to ask me for a good Acrobat scripting resource anymore, just go to PDFScripting.com and sign up for a year – it’s well worth the membership fee (and as Thom says in his tour video, no surprise at the end of the year, the membership does not automatically renew).

For a few years now Adobe has been telling 3rd party developers that the ADM (Adobe Dialog Manager) will be discontinued, and that existing plug-ins may have to be ported to something else. If I remember correctly, this started with Acrobat 7 or 8, but back then it was a soft threat – everything still worked, and there wasn’t much incentive to start porting plug-ins. However, with the release of the Acrobat 9 SDK the ADM related header files were gone, but ADM based plug-ins were still working (at least some of them).

The removal of the header files does send a strong signal, but what was an even stronger signal for me was that one of the ADM based plug-in I was working on was no longer working correctly on some versions of Windows.

As far as Adobe is concerned, ADM is no longer supported – that means there won’t be any bug fixes for it, but the plug-in has to work with Acrobat 9 on any Windows system that’s supported by Acrobat 9. So, what is a developer to do in such a situation?

Adobe does not give us much guidance in what to chose as a replacement for ADM. The most obvious choice is to stick with the native UI framework that comes with the operating system, but the advantage of ADM was that one could write UI code that would run in both Windows and Mac plug-ins. One of the sample plug-ins – wxPlugin – that comes with the Acrobat SDK is based on wxWidgets. To me that was a pretty strong hint that wxWidgets would be a good choice…

However, even though the Mac version of the SDK does come with the wxPlugin code and even contains a XCode project file, it does not compile. After some work, trying to come up with a combination of wxWidget configuration options and wxPlugin project settings, I was able to create an Acrobat plug-in that worked.

In order to “fix” the Mac’s version of the wxPlugin I first had to compile wxWidgets. Use the following configure command line to create the static wxWidget libraries that can be linked with the project:

configure CC=gcc-4.0 CXX=g++-4.0 LD=g++-4.0 --enable-universal_binary \
--disable-shared --with-macosx-sdk=/Developer/SDKs/MacOSX10.4u.sdk \
--with-mmacosx-version-min=10.4 --enable-debug

Just install the libraries and include files according to the instructions provided by Adobe.

A closer inspection of the plug-in code then revealed that the part that actually did anything was commented out for the Mac with #ifndef MAC_PLATFORM statements, so I removed those and the last thing to do was to remove the reference to the libexpat library – it is provided by the operating system and does not have to be provided by wxWidgets.

With a working environment on the Mac, wxWidgets is a viable alternative for ADM for either new Acrobat plug-ins, or existing plug-ins that need to be modified to make them compatible with the current version of Acrobat.

If your Acrobat plug-ins are still using ADM, now would be a good time to think about what to do about that… If you need any help, let me know.

Acrobat’s JavaScript is a great tool to extend the application, or to automate reoccurring tasks. There are several ways a JavaScript can be added to the application or a document (e.g. folder level scripts, validation scripts, event handling scripts, …), but regardless of how a script is written, chances are that the developer wants to test parts of the script in Acrobat’s Javascript console. This console window can be shown by either using the “Advanced>Document Processing>JavaScript Debugger…” menu item or Ctrl-J on Windows or Cmd-J on a Mac:

After the console or debugger window comes up, the user can then enter Javascript and execute it…

… that is, as long as a full keyboard with a numeric keypad is used. In Adobe’s documentation, we find the following instructions to execute Javascript typed into the console window:

The JavaScript console allows you to evaluate single or multiple lines of code. There are three ways to evaluate JavaScript code while using the interactive console:

• To evaluate a portion of a line of code, highlight the portion and press either the Enter key on the numeric keypad or press Ctrl + Enter.
• To evaluate a single line of code, make sure the cursor is positioned on that line and press either the Enter key on the numeric keypad or press Ctrl + Enter.
• To evaluate multiple lines of code, highlight those lines and press either the Enter key on the numeric keypad or press Ctrl + Enter.

That works fine as long as you have access to the numeric keypad, but on a MacBook or a MacBook Pro without that keypad. No key combination involving fn, ctrl, cmd or option with the Return or Enter key will result in the Javascript getting executed.

The virtual keyboard to the rescue: Mac OS comes with a handy keyboard viewer that allows us to send the correct key code to the application. To bring up the keyboard viewer, bring up the Mac OS System Preferences first and select the “Keyboard” category:

Make sure that the option “Show Keyboard & Character Viewer in menu bar” is selected. Once this is done, you can access the keyboard viewer from the menu bar:

Now comes the tricky part: Write some Javascript in the console window and place the cursor on the line you want to execute or select the snippet of the Javascript that should be executed. In the following example I’m using code from Adobe’s Javascript API documentation:

  var menuItems = app.listMenuItems()
  for( var i in menuItems)
    console.println(menuItems[i] + "\n")

With the console prepped, bring up the keyboard viewer and start pushing keys – real keys that is: Hold down the “fn” and the “control” key, then move the mouse pointer to the “Enter” key on the keyboard viewer and click it…

… and voila, the script gets executed:

This is not the most straight forward method, but at least it’s possible to use the Javascript console to execute code when using a MacBook.

If you’ve seen my resume – or talked to me lately, you know that I create Acrobat plug-ins for a living. When people hear that, they usually think something like “Don’t forget to pick up the dry cleaning” or “I need to bring my cat to the vet for the rabies shot”… Yes, I understand, this may not be the most exciting topic, but probably only because you don’t know enough about what these “plug-ins” are, so let me explain.

 

Adobe Acrobat is a very powerful tool, more powerful that most users actually realize. I wont go into any details about how powerful exactly – at least not today. Lets just say that it has something for everybody. However, you may need something in addition to what Adobe provides, something that still is in the general area of PDF. Adobe may not have considered your needs because either the target market for “your” feature is too small, or to far out there… Or you are so far ahead of everybody else that they have not even thought about that feature yet.

Adobe did however do a very interesting thing: They created an interface that allows 3rd party developers to create solutions based on Adobe Acrobat – using plug-ins. It is a very powerful interface, and hence not something that you can pick up in an afternoon. There are several thousand pages of API documentation that one needs to understand before a plug-in should be written.

A plug-in is – from a technical point of view – a module or library that gets loaded dynamically at runtime. Acrobat will scan it’s plug-ins directory and will load any modules it finds. Once loaded, such a plug-in can extend Acrobat by e.g. adding menu items, toolbuttons, or event handlers (e.g. a function that gets executed whenever a documents gets loaded).

 

Interestingly enough, the plug-ins directory of a fresh Adobe Acrobat installation is not empty… A lot of Acrobat’s functionality is actually implemented as plug-ins. You can verify that on a Windows system by temporarily disabling all plug-ins by holding down the Shift key when bringing up Acrobat. That will load the application without any plug-ins. When you compare the toolbar or the menu bar with a fully loaded application, you’ll see what portion of the Acrobat core functionality is actually implemented in plug-ins.

The plug-in interface has different abstraction levels (COS, PDE, AV, …). If there is enough interest, I will provide information about how to navigate that API, and how to structure a plug-in.

The Acrobat SDK is available for free from Adobe’s Acrobat Development Center.

Here are a few examples of commercially available plug-ins that I’ve used:

• Enfocus PitStop Professional:
  This is a preflight tool.
• Quite Imposing Plus:
  The best PDF based imposition tool that I am aware of.
• Enfocus Browser:
  Allows to review and change the internal structure of a PDF file.

No, this is not about my patent pending idea of a sheet splitter that turns duplex documents into simplex documents… This post is about a problem that comes up every now and then: When you scan a book or a magazine, chances are that you end up with two physical pages on your scanned image, and your document looks something like this:

Pages one and two are on the same scan, three and four are, and five and six and so on.

How can we split such a combined page into it’s two parts?

There are of course different solutions to this problem, some more complicated than others, some producing better results than others.

The most straight forward approach would be to write an Acrobat plug-in or a standalone application (e.g. using the iText library) that takes the source page, determines what needs to be copied to the new page that should represent the left half of the original page, and then just copy those page elements. With a scanned source document, this would potentially mean that the scanned image needs to be cropped and placed on the target page. Sounds complicated, and it is complicated. Is there an easier way to accomplish the same results?

[More after the jump]

If we have access the Acrobat, we can use JavaScript to mimic the behavior of the just described application. With Acrobat’s JavaScript, we do of course not have access to the page content elements, so we need to find a different way to end up with the same results.

JavaScript gives us access to the crop box of a PDF page (if you don’t know what that is, read up on page boxes in the PDF Reference), this means we can find out how big a page is, but also set the crop box to configure which part of the page should be displayed in the viewer, or should get printed.

So, if our combined page is 11×17″, and we want to extract two 8 1/2×11″ pages, we first need to “select” the left half of the page, and then the right half of the same page.

Here is the script that will do just that:
SplitPages.js

Copy that file to the Acrobat JavaScript directory – for Acrobat 9 on a Windows machine that would be

c:\Program Files\Adobe\Acrobat 9.0\Acrobat\JavaScript

ProcessDocument = app.trustedFunction(function()
{
// create a new document
app.beginPriv();
var newDoc = app.newDoc();
app.endPriv();

var i = 0;
while (i < this.numPages)
{
  newDoc.insertPages( {
  nPage: newDoc.numPages-1,
  cPath: this.path,
  nStart: i
});
newDoc.insertPages( {
  nPage: newDoc.numPages-1,
  cPath: this.path,
  nStart: i
});
// we did this twice so that we can then split each copy of the page into a left
// and right half.
i++;
}

In these few lines we copy every page from the source document (this.path, which is the path to the active document) to our newly created document – and we are doing that twice. This is necessary because we need to crop out the left half of the page for the first page, and the right half of the page for the second page. After this loop, we will have twice as many pages in our new document than we have in our source document.

if (newDoc.numPages > 1)
{
  newDoc.deletePages(0);  // this gets rid of the page that was created with the newDoc call.
}

Now that we have all the pages in our new document, we no longer need the blank page we got when we created the document. So, we delete it.

// at this point we have a documnent with every page from the source document
// copied twice

 for (i=0; i<newDoc.numPages; i++)
{
  // determine the crop box of the page
  var cropRect = newDoc.getPageBox("Crop", i);
  var halfWidth = (cropRect[2]-cropRect[0])/2;

var cropLeft = new Array();
cropLeft[0] = cropRect[0];
cropLeft[1] = cropRect[1];
cropLeft[2] = cropRect[0] + halfWidth;
cropLeft[3] = cropRect[3];

The previous few lines create a new Array. A page box is represented as an array of four values. We can now assign the partially modified values to the new page box. As you can see, three of the four values just are copies of the original crop box. Array element 2 however gets modified. It is the original X value for the lower left point of the crop box, and we add half of our page width to that number. This means, the new right edge of the modified page box is now at the halfway point between the two sides.

var cropRight = new Array();
cropRight[0] = cropRect[2] - halfWidth;
cropRight[1] = cropRect[1];
cropRight[2] = cropRect[2];
cropRight[3] = cropRect[3];

if (i%2 == 0)
{
  newDoc.setPageBoxes( {
  cBox: "Crop",
  nStart: i,
  rBox: cropLeft
});
}
else
{
  newDoc.setPageBoxes( {
  cBox: "Crop",
  nStart: i,
  rBox: cropRight
});
}
}
}
)

This is a bit tricky… Acrobat starts to count pages with page 0. The first page in the document is on the left half of our first sheet. All of a sudden, our first page is actually an even page number (0), and not like in “normal” books an odd number (1). This means that for all even numbers we need to crop the left half, and for all odd numbers we need to crop the right half.

We test for “evenness” by performing the modulo operation on our page number. If the result is 0, we know we have an even number, so we can use the left side crop box. If the operation returns 1, we are dealing with an odd page number, and we will use the ride side crop box.

The new crop box gets applied with the doc.setPageBoxes() method.

// add the menu item
app.addMenuItem({
  cName: "splitPagesJS",     // this is the internal name used for this menu item
  cUser: "Split Pages",       // this is the label that is used to display the menu item
  cParent: "Document",              // this is the parent menu. The file menu would use "File"
  cExec: "ProcessDocument()",  // this is the JavaScript code to execute when this menu item is selected
  cEnable: "event.rc = (event.target != null);",       // when should this menu item be active?
  nPos: 0
});

Almost done… We’ve implemented the functionality to split the pages, now we just need a mechanism to actually start our little program. I’ve chosen to create a menu item under the “Document” menu. That menu item is only available (not grayed out), if we have an active document.

Disclaimer: Of course, there is no such thing as a sheet splitter, and therefore there is no patent application. It’s a joke.

I’ve been using Twitter more over the last few weeks – this is pretty obvious when you take a look at the graph from TwitterCounter.com:

Once I started to tweet more, my follower count went up.

While playing around with different Twitter tools, I came across MyTweet16.com, which allows you to display the first 16 tweets of any Twitter user. I of course was curious about what I had to say when I first signed up for my account.

What I found was pretty interesting: For my very first tweet, I did not use any of the “normal” ways to use Twitter: It was not the web interface or any of the established Twitter clients – instead, I used a program that I wrote myself. I completely forgot about that. Who else can say that they tweeted first with something they created (besides Biz Stone and Jack Dorsey, the founders of Twitter)?

I used the book Creating Mashups with Adobe Flex and AIR (Friends of Ed Abobe Learning Library) to get some exposure to Flex, and the first few examples in the book are about using the Twitter API.

So, without any further ado, here is my first tweet (copy&pasted from MyTweet16.com:

Playing with Flex for the first time (that's how I twittered this). 12:33 PM Jun 3rd 2008

Please follow me on Twitter.

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”: