How We Did It: Part 4 – The Ultimate Tourney Guide

| No Comments

This article is Part 4 of 5. Please start with Part 1 if you have not done so already.

In Part 3 of this series, I discussed the new Acrobat 9 security model and its impact on the "Ultimate Tourney Guide" project. But, what if you hadn’t already installed Acrobat or Reader 9? Because we wanted to create an outstanding first-open experience, we wanted users of earlier versions to see something better than just the update dialog and a static file. So, we added an image to the first page that only Acrobat 9 or Reader 9 can hide. This made it so that the PDF file would be seen properly in the right version but degrade beautifully if not. We used Acrobat forms functionality and a little JavaScript to pull that off. In this article, I’ll tell you how we did it.

Hiding and Showing PDF Content:
What Were Our Options?
When we were examining how to create a file that displayed one way in Acrobat and Reader 9 and a totally different way in earlier versions as well as non-Adobe viewers, there were several options. We needed to determine which would work best for this particular project. Please note: any of the following options are a good way to do this. Determining which is the best for your project will be dictated by your specific needs.

There are two things that we needed to be able to do programmatically with the PDF file in order to achieve the effect that we wanted; detect the version of Acrobat being used and to cause some sort of object to display or not.

Detecting the Version:
This part is easy. The app object in the Acrobat JavaScript API can be used to detect the viewerVersion property of the application that the PDF file is being viewed in. We added this kind of code to the Document JavaScripts outside of any function so that it runs just as the document opens.

if (app.viewerVersion >= 9)
{
//do the version 9 or higher code
}
else
{
//do the lower version code
}

Note: As a best practice, you will also want to check the viewerType and viewerVariation. The viewerType and viewerVersion can be used to detect if your PDF file is being viewed in an Adobe product. Most non-Adobe viewers do not have a JavaScript interpreter for PDF files and the ones that do have an incomplete implementation.

Now that we can detect the version number, we can take action on an object that we want to hide or show depending on what the version number is. The question now is, “Which technique do we use?”

Hide and Show a Layer:
We added layers to the PDF file format in version 1.5 and a Layers panel to control their visibility in Acrobat 6. Additionally, Acrobat JavaScript can be used to hide or show a layer and all you need to know is the name of the layer. In the Acrobat JavaScript API, layers are referred to as OCGs or optional content groups and their visibility can be controlled by setting the state property.

Because we used Buttons on the first page and we wanted those buttons to not show in earlier versions of Acrobat or Reader, we decided not to use this technique for the Ultimate Tourney Guide first page. The Z-Order of buttons is on top of the page content and OCGs are part of the page content… they’re just optional.

Hide and Show a Template:
Templates are named pages within the PDF document. These pages may be hidden or visible and can be copied onto an existing page as an overlay or “spawned” as a new page using JavaScript. We are using this technique with some other version-dependent projects but in this particular case, we decided to use Buttons to achieve the effect we wanted in the Ultimate Tourney Guide.

Hide and Show a Button:
We decided to use a button that covered the first page of the PDF file entirely. Buttons in PDF files can display on the page with a label, as an icon, or both. You can create button icon from any PDF file and control its behavior; read how.  We created a PDF file (right) that was the exact same size as the first page, created a button on the first page and then imported that PDF file as the button icon for that button. By default, this button is visible which is what we want. With the following Acrobat JavaScript in the Document JavaScripts area we can hide the button if the viewerVersion is higher than 9. This takes care of the Adobe Acrobat and Reader versions 9 and those that are less than 9.

if (app.viewerVersion >= 9)
{
this.getField(“v8_button”).hidden = true;
}

Button icons in non-Adobe viewers:
Because of the way that the button icon appearance is stored in a PDF file, non-Adobe viewers will be able to display the default button icon even if that viewer doesn’t understand that it is a button. Additionally, the fact that the Z-Order of form fields and buttons is on top of the regular PDF page content, the button will also completely cover anything that sits below it. Now we have a solution for displaying the upgrade message in non-Adobe viewers.

Conclusion:
By using some very basic Acrobat JavaScripts, we were able to customize the experience for people who use Acrobat or Reader 9, lower versions of Adobe’s viewers as well as non-Adobe viewers far beyond what is generally available in the various products. In the final part of this series, I’ll revisit the use of buttons but this time I’ll discuss how we created that stunning first page using the simplest of techniques.

Read Part 5