About PDF Portfolios and Navigators
Adobe Acrobat allows you to create PDF Portfolios, which are PDF files that contain other files, called attachments, and manage those attachments. These attachments can be in different formats, of different types, and created by different applications. The original files retain their individual identities when they become part of the single PDF Portfolio file. Each attachment can be opened, read, edited, and formatted independently of the other attachments in the PDF Portfolio.
The presentation and management of the attachments in a PDF Portfolio, and any actions taken on them, such as viewing and editing, is managed by an PDF Portfolio Layout, or Navigator. In other words, a Navigator is a Flash front-end for the collection of content in a PDF Portfolio. It defines animations, colors, card styles, fonts, headers, footers, background, preview states, treatment of specific doc types and more. You create Navigators in Adobe Flash Builder by using the Acrobat Portfolios SDK.
A Navigator can include a range of interactive features, including user interface components (widgets), animation, and localized strings. It can also contain media files-such as video clips, images, and mp3 files,-to provide a rich media experience. The Navigator interacts with PDF Portfolios through the Acrobat application.
Acrobat Pro allows you to apply PDF Portfolio Navigators to a PDF Portfolio. When applying a Navigator, you can choose from the Navigators installed with Acrobat Pro, or you can apply a custom Navigator that you or others develop. When a Navigator is applied to a PDF Portfolio, it becomes part of that PDF Portfolio. That is, it is part of the PDF document that contains the PDF Portfolio. Users of Acrobat X or Adobe Reader X can then view the PDF Portfolio using the embedded Navigator. Acrobat users have the ability to update the PDF Portfolio, and Acrobat Professional users can edit the Navigator properties.
The Acrobat Portfolios SDK provides you with the tools to create your own custom Navigators. It contains two rich ActionScript APIs you use to create customized Navigators. It also includes three Flash Builder plug-in wizards that automate key steps in Navigator development:
- The initial creation of a Navigator project
- Launching a debugging session for the Navigator in a previewer application, or in Acrobat
- Packaging the completed Navigator into a single file for use with PDF Portfolios
There are a couple of concepts you need to understand when building Navigators. Navigators are applications that are called from a host application: Adobe Acrobat. They provide the presentation interface for PDF Portfolios by working in conjunction with the host application. Acrobat has two types of interfaces for the contents of a PDF Portfolio, a tabular format and a more graphical view which is controlled by the Navigator. When switching between these control is passed between the host application and the Navigator.
The Navigator has a preview concept for the contents of the PDF Portfolio. A Navigator user can preview the attachments that are included in the PDF Portfolio without having to leave the Navigator. Depending on the type of attachment that is part of the PDF Portfolio, the user can view and even edit the attachment's contents. Any changes made are saved in the PDF Portfolio.
Types of PDF Portfolio Interfaces
Acrobat provides two ways of viewing the contents of a PDF Portfolio, a layout view and a files view.
- The layout view is a graphical representation. Attachments are shown as thumbnails. The user can navigate through the list of attachments, which can be presented in a variety of visual styles: linearly, in a grid, as a "wave," free form placement, and so on. Navigators control the display and actions of the PDF Portfolio when it is in layout view.
- The files view is a table with one row for each attachment. The row displays the details for that attachment, such as name, size, and description. If the attachment is a folder, you can double click on the folder to display its contents, also in a tabular format. This view is not controlled by the Navigator. It is controlled by Acrobat. Changes may be made to the PDF Portfolio when it is in files view.
Preview the Contents of a PDF Portfolio with a Navigator
Although Navigators were introduced with Acrobat 9, you could not preview the contents of a PDF Portfolio with a Navigator. Instead, in Acrobat 9 you used Acrobat to preview the contents of your PDF Portfolio. This could confuse the user, leaving them unsure of what application they were working in.
In Acrobat X, the new Navigators provide preview functionality. This keeps the semi-transparent Navigator in the background, and uses transitions and skins as clues that you are still in the Navigator context. In addition, there is a large close button; when you press the close button you exit the Navigator preview mode and return to the normal Navigator viewing mode.
When you are in preview mode, you have access to commands that act on the attachment you are previewing, including:
- See attachment information
- Go to the next or previous page of the attachment, if the attachment is a PDF file
- Extract the attachment from the PDF Portfolio
When you are in preview mode you still have access to commands for navigating within the PDF Portfolio without leaving the previewer. For example, you can go to next or previous PDF Portfolio attachment.
- The Acrobat 9 style of previewing is still available to developers in the Acrobat Portfolios SDK.
How to Create a Custom Navigator
Adobe Acrobat Portfolios SDK greatly simplifies the process of creating custom Navigators. It's wizards automate the process of creating an initial working Navigator, debugging your Navigator, and packaging the completed Navigator along with its resources as a Navigator (NAV) file.
To build Navigators using the Acrobat Portfolios SDK the following must be installed on your system:
- Adobe Acrobat Portfolios SDK
- Adobe Flash Builder 4.0.1 or later (available at http://www.adobe.com/cfusion/tdrc/index.cfm?product=flash_builder)
- Adobe Flex 4.1 SDK (available at http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4)
- Adobe Acrobat X Pro or later
The development workflow
To create a custom Navigator you need to do the following:
- Install the Adobe Acrobat Portfolios SDK plugins and AIR application in your Flash Builder programming environment. See Installing Acrobat Portfolios SDK for instructions.
- Install the acroFlashDebug plugin into Acrobat X. See Installing Acrobat Portfolios SDK for instructions.
- Run the Create Navigator Project wizard
- Use ActionScript, Flex 4, and the Acrobat Portfolios SDK to write your Navigator
- Test and debug your Navigator using the Debug Adobe Navigator wizards
- Export your Navigator as a Navigator (NAV) file.
- Import your Navigator into Acrobat, where it is available to apply to PDF Portfolios.
There are two separate application programming interfaces (APIs) you use to create custom Navigators:
- com.adobe.portfolio.api, known simply as the Portfolio API
- com.adobe.portfolio, known as the Portfolio Framework
com.adobe.portfolio.api, known as the Portfolio API, is a lower level API, first introduced with Acrobat 9 that has been updated to work with Acrobat X. See Portfolio API for information on this API.
com.adobe.portfolio, known as the Portfolio Framework, is a new, higher level API, that is built on top of com.adobe.portfolio.api. It provides a layer of abstraction between the Navigator and its host application (Acrobat) to maximize flexibility on both sides and to give access to the host application of the Navigator's configurable properties, without the. It provides extensive support for skinning the various Navigator components. See Portfolio Framework API for information on this API.
When you build a Navigator using the Portfolio Framework, the representation and behavior of your Navigator's properties are controlled by the Navigator. The host application has no knowledge of how properties are stored, or what effect they have on the Navigator. The host simply allows the Navigator to specify it's properties through a collection of property interfaces defined in Portfolio Framework. The host application use these interfaces to get and set properties, with the implementation handled by the Navigator.