Flash Buttons for PDF documents
by Thom Parker, Software Developer/Adventurer, WindJack Solutions, Inc.
Scope: Acrobat 9.0 and later
Category: Form/Document Scripting
Skill Level: Intermediate and Advanced
Prerequisites: Acrobat JavaScript/Flex 3 Programming
Acrobat 9 has brought some great new features to Acrobat and PDF. But for my money, the best one is the Rich Media Annotation. By “rich media,” Adobe means Flash. So these annotations are really Flash players. This is not the same as the existing Screen Annotation that plays movies (and Flash, of course), and on the surface it looks much poorer. It has way fewer JavaScript properties and methods, and the UI for setting up a Rich Media Annot is much simpler than for a Screen Annot. But don’t be deceived—all those fancy features for handling the Screen Annot are there because the Screen Annot is a generic interface to all manor of media types and players. It relies entirely on users having the correct media player on their systems for the media being played by the PDF. Not the most reliable of situations, and a constant headache for anyone trying to put a movie into a PDF.
So what makes the Rich Media Annot any different from the old stuff? Drum roll please… The Flash 9 player is built into Acrobat 9 (the version numbers are a coincidence). Playing media on an arbitrary user’s system is no longer a guessing game. This is truly a happy moment for all creators of multimedia PDFs. The reason it’s so much simpler than the Screen Annot is that there is no need to worry about what users have on their systems. The player is built-in, all media is Flash and all the playback controls and interactivity are built into the Flash file itself. Quite literally, there is no need for any of this functionality on the PDF side, or on a user’s system.
And it gets better. Because the Flash player is tightly integrated into Acrobat, they can talk to each other. This is my real interest in the Rich Media Annotation. Acrobat JavaScript can now communicate directly with ActionScript in Flash. This one thing opens up the barn doors. Flash is a highly interactive and diverse environment, whereas Acrobat is largely limited to basic document and form types of interactivity. Not to say this is a bad thing. Acrobat and PDF do all the things required of documents and forms, but whenever developers try to step out of this box, they hit walls. Multimedia is one example of a contentious issue that the built-in player fixes. But the biggest concern for me is user interface controls, and this is where the bridge between Acrobat JavaScript and ActionScript really shines. We are no longer limited to the eight form field types and standard UI controls (such as popup menus) built into Acrobat. Anything that can be created in Flash — which is just about anything — can now be used as an active control in a PDF document.
Building Flash UI controls for PDF
For interactive UI features, there are two ways to go with the new Rich Media Annotation — as an input control or as a display area. An input control could be anything from a button to a calendar popup. A display could be anything from simple text to a fancy graphical display (a pie chart, for example). Flash provides a world of options. And because the Rich Media Annotation can have a transparent background, we are not limited to rectangular UI elements.
Enough hype! Now let’s talk about the realities. In the past, programming interactive features for PDF meant Acrobat JavaScript working on native PDF features. The only tools we needed were Acrobat Professional and a basic knowledge of JavaScript. With the Rich Media Annotation, that’s all changed. Now we also need a Flash development tool, such as Flash or Flex, and a basic understanding of the wonderful new world.
Another issue is that since part of the development happens outside of Acrobat, the development and debug workflow is handicapped, i.e. , Acrobat’s JavaScript Console doesn’t help to find and fix problems in the Flash, or provide us with a quick way to test out ideas. Also, the Flash or Flex environment is good for debugging issues purely inside the Flash media, but doesn’t help us with communication problems between it and the PDF.
Given these development issues, it’s a good idea to start simple. Which is exactly what we’ll do in this tip.
Building a button in Flex for use in a PDF
Communication between ActionScript in a Flash and JavaScript on a PDF works in both directions. Acrobat JavaScript can call functions in the Flash that have been specially registered for this purpose. But on the Flash side, ActionScript has full access to the entire Acrobat JavaScript environment.
A good, simple place to start exploring this connection (and also a practical one) is by creating a Flash button that can be used on a PDF. Button communication is one-way. The user clicks on the button, and the button tells JavaScript code in Acrobat to do something. The advantage of using a Flash button over an ordinary PDF form button is the Flash button can have fancy graphics that are more interesting, entertaining and/or communicate more information to the user. But to start out, we’ll stick with a simple, plain button just to see how it all works.
Flash tools
I’m not a graphic designer. I’m a programmer, so my Flash tool of choice is Flex Builder 3, which is similar to other application programming tools I’ve used. However, the only important thing here is to be able to create a SWF file containing ActionScript that will call a JavaScript function in the PDF. For communication between JavaScript and ActionScript, the SWF must be Flash 9 compatible and use ActionScript 3.0. You don’t need the Flex Builder tool to create Flex applications. In fact, Adobe gives away free command line tools for creating Flex Applications. Or, if you’re familiar with Adobe Flash, you can use it. This tip is not about using any of these tools. It’s up to you to figure out how you’re going to create the actual SWF file.
MXML
Flex applications are built on what’s called the Flex Framework. I don’t want to get too technical, but this framework is a set of ActionScript Classes. Classes in ActionScript are very similar to the concept of Objects in JavaScript. These Flex Classes are built on top of a version of Flash called Flash MX.
In Flex, a class can be instantiated (declared) with ActionScript code, or with its equivalent XML tag. In fact, it’s common to build a Flex application by using mostly XML tags. All of the XML tags used to represent equivalent framework classes are prefixed with “MX,” so the Flex XML is commonly referred to as MXML. The tags give the application code a visual structure representing the mostly static parts of the program, such as the physical layout and controls (buttons, text fields, etc. ). ActionScript code is usually reserved for the active and dynamic parts of the application.
First button
The following Flex code creates a Flash application containing a single button. When pressed, this button calls a function in the PDF named “DisplayPopup,” and passes it a single input parameter:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="80" height="20" backgroundAlpha="0">
<mx:Script>
<![CDATA[
public function DoButtClick():void
{
ExternalInterface.call("DisplayPopup","Hello");
}
]]>
</mx:Script>
<mx:Button click="DoButtClick()" label="Button" width="80" height="20"/>
</mx:Application>}
The first line of this code tells us that what follows is official XML. In fact, it’s MXML. The next line instantiates a Flex application object using the “mxApplication” tag. Inside the application are two components. The first one is a script, indicated by the “mx:Script” tag. The script defines a single function used by the next component, which is a button. The button calls the function in its click event. For our purposes, this is about as bare bones as it gets.
There are a couple of things to note about this code. First, notice that the size of the button — given by the “width” and “height” attributes — is identical to the size of the application. The application size is the amount of room the Rich Annotation will need to take up on a PDF page. We don’t want any wasted space here, so it should be as small as it can be. The next thing to notice is the application’s “backgroundAlpha” attribute. Alpha is the same thing as transparency, where a value of 1 is opaque and a value of 0 is completely transparent. We don’t want anything except the button to appear on our PDF, so it’s important to make the application’s background clear. If you’re already familiar with JavaScript, you’ll notice that ActionScript looks a lot like JavaScript. That’s because it basically is JavaScript, with some fancy extra features. Once this MXML is compiled into a SWF file, we’re ready to place it on a page in our PDF.
Inserting a Flash button into a PDF
Open or create a PDF file in Acrobat Professional 9. The function in the SWF calls a function in our PDF named “DisplayPopup.” So the first thing we should do is create this function. From the Advanced menu, select “Document Processing > Document JavaScripts.” This will display the Document Level Script dialog. Enter “DisplayPopup” into the “Script Name” box and press “Edit.” This action automatically creates an empty function with the name we want. Modify this code to look like the code below:
function DisplayPopup(cMsg)
{
app.alert(cMsg,3);
}
The “DisplayPopup” function has one input parameter, which matches the function called in the Flash; it displays an alert box. However, there’s nothing stopping us from making the function do just about anything. It’s simply a function that’s called from the Flash. What it does is up to us. I only used the alert box as an easy example. The next thing we need to do is add the SWF file to a page in the PDF. Select the Flash tool from the “Tasks” toolbar (Figure 1).
Figure 1- Selecting the “Flash Tool” from the Tasks toolbar in Acrobat 9
Use the Flash tool to draw out a square on the PDF. The size is unimportant because it will be automatically resized when the SWF file is imported. After you draw out the rectangle, the Flash dialog will be displayed. Enter the location of the Flash file, then make sure the “Snap to Content Proportions” check box is selected. Then select the Advanced Properties check box (Figure 2).
Figure 2 – Entering data into the Insert Flash Dialog
There are three options on the Advanced Flash Properties dialog that need to be set (Figure 3).
Figure 3 – Setting up the Advanced RichMedia Annot properties.
First, the Flash needs to start running as soon as possible. To the user, this is supposed to look just like a regular button on the PDF. We don’t want them to have to click on it to make it start working. So the “Enable When” and “Disable When” options have to be set to start and stop the Flash animation when the page is opened and closed. Lastly, the Rich Media Annot needs to have a transparent background so it doesn’t hide anything it shouldn’t.
That’s it. Now save, close and re-open the PDF file. If everything was done correctly, the button will appear active and clicking on it will display an Alert box with the word “Hello” in it.
I’ve created an example PDF with four sample buttons in it, FlashButtons_Sample.pdf. The first sample is a regular PDF form button with a rollover effect. It’s provided for comparison. Two of the examples were built with Flex 3, and the last one was built with Flash 9. I’ll repeat again, I’m not a Flash programmer, so the Flash file is a bit of a kludge. I downloaded a free Flash project file from the internet (ffiles.com) and modified it for Flash 9/ActionScript 3.0 and to work in a PDF.
More info:
Besides information on the Adobe website, there is a wealth of information on the Internet about programming Flash and Flex. Unfortunately, there isn’t much specifically about Flex 3 and ActionScript 3.0, since these are the newest incarnations of these products. It’s even more unfortunate that there seem to be major incompatibilities between different versions of these products. Many of the techniques used to program Flash in previous versions are not forward-compatible.
This is really new stuff, so there is very little information as yet on two-way communication between Acrobat JavaScript and ActionScript. In fact, at the time of writing this article, the official documentation for Acrobat 9 JavaScript isn’t even out yet. Surely when the Acrobat SDK does come out, it will have documentation and samples. You can look for it here:
http://www.adobe.com/devnet/acrobat/
Here are some links to existing information on the new RichMedia Annotation. Not all of them are relevant to our topic, but this is about all the current stuff out there.
Marc Liron article on Flash Movies in PDF
http://www.marcliron.com/adobe-acrobat-9-and-flash-video.html
Joel Geraci's Blog on Reader 9 with example of Flex Chart
http://blogs.adobe.com/pdfdevjunkie/2008/07/hot_on_the_heals_of_acrobat_co.html
D. P. Story's example of Rich Media Annotation in PDF- charts
http://www.math.uakron.edu/~dpstory/rmannot.html
Adobe Consulting Blog on the Rich Media Annotation
http://blogs.adobe.com/acdc/acrobat/
Ali Hanyaloglu's Blog on Rich Media Annotation for commenting on video
http://blogs.adobe.com/thesamepage/2008/06/commenting_on_video_still_adds.htm
