The Flex Developer's Guide to Acrobat


This guide is for developers using Adobe Flex Builder 3 who want to create SWF content that is intended to play inside PDF documents using the Flash Player in Acrobat in Adobe Acrobat 9 or higher.

Note: If you have already read The Flash Designer’s Guide to Acrobat, much of this content will look familiar since the capabilities of the Flash Player in Acrobat are the same. You may want to skip to the section called ScaleMode and the Flash Player in Acrobat

One of the great new features of Adobe Acrobat 9 Pro and Pro Extended is the ability to add SWF-based Rich Media Annotations (RMAs) developed in Flex (or Flash). These SWF files can be placed in a PDF document using the new Flash Tool in Acrobat 9 and play using the Flash Player in Acrobat. The Flash Player in Acrobat provides greater security and consistency for Flash playback inside any PDF document. For those of you that attempted to use Flash content in a PDF document in earlier versions of Acrobat, you’ll remember that the user experience wasn’t all that great. Acrobat 9 provides tight integration between the PDF document and the RMAs well as other content types that run in the Flash Player in Acrobat such as FLV and H.264 encoded video.

Placing Your SWF Content as a Rich Media Annotation in Acrobat

Placing a simple SWF file into a PDF document is as easy as adding it to an HTML page. However, there are a few additional settings that are important to get right in order to create the exact experience you want for your end users. The most important being the "Playback Style"

There are two ways to play the SWF in Acrobat or Reader, on the page or in a floating window.

Click to Zoom

The floating window has certain advantages when you need the SWF to be present regardless of what page you are on in the PDF file.

When the SWF is played on the page, you are able to use the Acrobat commenting features to review and markup the interactive content. More on that a little later in this article.

Tip: If you intend to play the SWF on the page, select the the Flash tool from the toolbar and double-click on the PDF page rather than dragging out a marquee. By double clicking and then selecting the SWF from the dialog box, the SWF will be placed at actual size and the rectangle for the Rich Media Annotation will be the right size.

Note: Read “Add multimedia files to a PDF” to learn how to add RMAs to PDF files using the new Flash tool rather than the legacy multimedia object.

You can either embedd the SWF in the PDF document by selecting it from your hard drive or you can reference the SWF via a URL. Three types of URLs can be used: RTMP, HTTP, and HTTPS. Flash Media Servers (FMS) use RTMP to host FLV files and H.264-compliant media files. On HTTP and HTTPS servers, FLV files and H.264-compliant MOV and MP4 files are supported.

One advantage to referencing the SWF via a URL is that you can update the SWF at any time without needing to update the PDF file and then redistribute it. However, there are security restrictions associated with this approach so you may not want to use this method unless you understand the desktop environment of your users. I’ll talk more about these security restriction a little later in this arcticle.

In the "Insert Flash" dialog you have the option of checking "Show Advanced Options". While not absolutely necessary, I always use the advanced options because I want to control the exact experience my end-users see. You’ll see three tabs where you can change the behavior of your SWF when running in the Flash Player in Acrobat.

The Launch Settings tab

Use these settings to determine how the media is started and stopped, where it is displayed, and what is displayed when the media isn’t running.

Activation Settings
Select options to determine when the media is played and stopped. From the Playback Style menu, select "Play Content In Floating Window" to have the SWF run in a window over the page. Content in a floating window enables users to read the page and interact with the SWF at the same time. The floatinng window will always open up in the upper right corner of the Acrobat or Reader UI, you have no control of it’s initial position however, the width and height settings allow you to specify it’s size.

Border Width
"Border Width" creates a black border around the SWF. If you are playing the SWF in a floating window you’ll need this border so that users can easily move the window around, resize it or close it.

Poster Image
The "Poster Image" allows you to specify an image that you want to be displayed when the SWF content is not activated. Acrobat will create a default "Poster Image" for you but I typically don’t find it satisfactory (though it is a very good guess at what I might want).

The Flash tab

"Pass Context Menu Click to Flash Movie" allows Flex developers to replace the Acrobat context menu with the context menu of the originating SWF file. When the user right-clicks the SWF file, the available options are from the originating file.

FlashVars work exactly the same way in Acrobat as in HTML.You can pass FlashVars through this dialog if you always need the same variables. If you need to pass FlashVars at runtime, be sure to read the section on "Communicating with Acrobat and the PDF document" later in this article.

The Resources tab

If your SWF file requires any resources that are externally referenced via relative URLs like images, style sheets or other SWFs, and you are embedding the SWF in your PDF file, use the "Resources" tab to additionally embed all of the externally refererenced files that are required to run the SWF. Think of the PDF file as your server and use this tab to "upload" everything that your server would need to play the SWF.

Note: If your SWF is not functioning properly inside of Acrobat it is most likely a failure to embedd all of the required resouces. See the section below, "Development Restrictions", for the next most likely reasons.

ScaleMode and the Flash Player in Acrobat

The Flash Player and specifically, Flash Player in Acrobat, support various "scaleModes". The scaleMode property tells the Flash Player how to scale what’s playing inside it.

The four possible modes are…

  • StageScaleMode.SHOW_ALL–The entire Flash application is visible in the specified area without distortion while maintaining the original aspect ratio of the application. Borders can appear on two sides of the application.
  • StageScaleMode.EXACT_FIT–The entire Flash application is visible in the specified area without trying to preserve the original aspect ratio. Distortion can occur.
  • StageScaleMode.NO_BORDER–The entire Flash application fills the specified area, without distortion but possibly with some cropping, while maintaining the original aspect ratio of the application.
  • StageScaleMode.NO_SCALE–The entire Flash application is fixed, so that it remains unchanged even as the size of the player window changes. Cropping might occur if the player window is smaller than the content.

If you want your SWF to scale it’s content along with the PDF page when you zoom in and out, the scaleMode of your application must be set to "StageScaleMode.EXACT_FIT". More importantly, this setting allows Acrobat to print the PDF with your SWF scaled properly on the page. If you intend your SWF to only be played in a floating window, then the scaleMode is not a concern.

Setting the scaleMode is pretty simple in Flex but it must be done after the stage object exists otherwise you get the "Cannot access a property or method of a null object reference" error. The way I do it is to add the following code to the "mx:Application" tag.

applicationComplete="stage.scaleMode = StageScaleMode.EXACT_FIT;"

The example PDF below will illustrate what a difference the scaleMode makes. In the PDF, the chart on the left uses the default scaleMode setting, the one on the right uses EXACT_FIT. Because the file is set to open at 100% zoom, both will look correct at first but then try zooming in and out of the document and you’ll see what how the scaleMode affects the display.

ScaleMode Example PDF

Development Restrictions

Rich Media Annotations in Acrobat and Reader use an embedded Flash Player runtime that is independent of the Adobe Flash Player installed on the system. However, not all objects allowed in SWF content playing in a network or web environment are allowed when playing inside the Flash Player in Acrobat; most significantly, SharedObjects, LocalConnection, FileReference and and user initiated sockets (though that restriction does not apply to RTMP streaming). However, there are Acrobat corollaries to the first two. If you need this sort of functionality, you’ll also want to be sure to read the section on "Communicating with Acrobat and the PDF Document" for implimentation advice.

Local Shared Objects:
SharedObject is disabled in the Flash Player in Acrobat. Instead you can use a "JavaScript for Acrobat" object called "global". "Global" is a JavaScript object that allows you to share data between documents and to have data be persistent across sessions. Such data is called persistent global data. Global data-sharing and notification across documents is done through a subscription mechanism, which allows you to monitor global data variables and report their value changes across documents. Each time a global variable is written to, the origin which set it is remembered. Only origins that match can then access the variable. For files, this means only the file that set it, having the same path it had when the variable was set, can access the variable. For documents opened from URLs it means only the host which set it can access the variable.

You can use a combination of the ExternalInterface Object and JavaScript for Acrobat to store and retirieve data from the global object. See the links at the end of this article to learn how.

is disabled in the Flash Player in Acrobat. However, again, you can use a combination of the ExternalInterface Object and JavaScript for Acrobat to communicate between SWFs running in the same PDF file. I’ve got a Flex tutorial and example here.

Flash Player in Acrobat Sandbox Security Model

Your SWF is allowed to use resources that were embedded during the authoring of the PDF file, but is restricted from accessing resources external to the document except to support streaming FLV files or to access trusted URLs. In all cases, a SWF running in Acrobat is subject to both Acrobat and Flash Player security rules. Acrobat provides the first layer of security features. The operation fails if Acrobat disallows the access. If it is allowed by Acrobat then it is checked against the security rules of Flash Player. The operation fails if Flash Player disallows the access. External Access is permitted only if both Acrobat and the Flash Player allow it.

If you are creating PDF files with dynamic content that is not wholely embedded in the PDF file itself, you’ll need to read this white paper and this blog entry.

Advanced Functionality Available to SWFs running in the Flash Player in Acrobat

In addition to the Flash Player in Acrobat providing greater security and consistency for SWF content playing inside of PDF files, it also has built-in functions that take advantage of features found only in Adobe Acrobat and Adobe Reader.

Saving State and Commenting

With a small amount of coding, you can keep the state of your SWF persistent in the PDF so that when the file is saved then re-opened, your SWF looks exactly the same. You can also do the same sort of thing except you store the state in a comment that was made on top of the SWF.

Communicating with Acrobat and the PDF Document

Acrobat’s scripting language is JavaScript. In order to trigger events in an embedded RMA, you’ll need to call the exposed ActionScript functions inside it. If you know how to communicate between an HTML page in a browser and the Flash browser plug-in, this will feel pretty familiar.

To call Acrobat methods from the SWF, you’d use just like you would with HTML. You can call any Acrobat method in the Acrobat JavaScript SDK. You can also call any methods that are in application level or document level JavaScripts and you can also use "eval" to send JavaScript into Acrobat from ActionScript and the return value of that method in Acrobat will be returned to your ActionScript method.

For a complete discussion of these advanced functions, please see my 5 part series called "Working with Rich Media Annotations".The series starts with the basics moves into more advanced topics and includes examples and source code for Flex Builder 3.

Leave a Comment