Your First Navigator Project

UPDATED 6/16/2011

  • All screen shots reference Flash Builder 4.5
  • All projects and examples are build with Flash Builder 4.5

This article is part one of a series and builds on exercises and concepts presented in the introduction to the series. If you have not already read the introduction installed Flash Builder 4, installed Adobe Acrobat X and set up the Acrobat X Portfolio SDK successfully please stop reading this article now and go to the Developing Custom PDF Portfolio Layouts using Flash Builder 4 article.

Creating a Navigator Project

You create a new Navigator project using the create Navigator project wizard that is part of the Acrobat Portfolio SDK. If you use the New Navigator Project wizard to create your Navigator project, it provides you with a working Navigator that can be compiled immediately with no additional codeing. This basic new Navigator project implements the key elements of any good Navigator:

  • It creates an instance of the Navigator class
  • It adds standard visual components to the Navigator: a background, header, a skinnable data container for the attachments, a MiniNavList component, a preview component, and scroller.
  • It adds non-visual components such as an AttachmentDropManager to handle drag-and-drop addition of attachments.
  • It adds states (loading, empty, and normal) and transition effects for state changes.
  • It handles the initialize event, so that the Navigator is properly connected to Acrobat.

To create your first Navigator project do the following.

  1. Go to File -> New -> Other.
  2. In the New dialog box select Adobe Navigator -> Navigator Project and click the Next button.
  3. In the Adobe Acrobat Navigator window enter a project name for your new Navigator project, the examples in this article use the name “MyFirstNavigator”. The folder field shows you where the files for your new Navigator project will be located.
  4. Click Finish. The wizard generates all the necessary files for your Navigator project, including a navfiles folder. This folder contains the additional files that are packaged with the .SWF file you build to create the .NAV Navigator file.
  5. Right-click on the new MyFirstNavigator Project folder in the Package Explorer and select Properties.
  6. If you are using Flash Builder 4.5 you must also set the Flex Compiler to use the Flex 4.1 SDK. You should have already installed this in the previous article.
  7. Select Run/Debug Settings then click the New button and select Adobe Navigator.
  8. Click the OK buton. The Edit Configuration dialog will appear.
  9. Accept the defaults and Click the OK button.
  10. Close the Properties dialog by clicking the OK button.

You are now ready to extend and customize your Navigator project. To customize your Navigator you can change the properties of the initial components, add to or replace these components with alternatives, and apply your own skins.

The default Navigator Project is very similar to the “Click-Through” Navigator that comes with Acrobat Pro X. The major difference is that it lacks the “Show next file” and “Show previous file” buttons. As the first customization in this series of tutorials, we’ll add these buttons.

Adding Components

The fundamental package for implementing Navigators is com.adobe.portfolio.api. This package provides the low-level interfaces and classes for Navigators.

The Portfolio Framework is a set of packages for implementing Navigators that are at a more abstract level than is com.adobe.portfolio.api. The Portfolio Framework provides more powerful classes for you to use. These classes have much of the design work already coded, so they are not as flexible as the low-level API, but they give you considerable power and contain a feature rich set of classes to use. Like com.adobe.portfolio.api these packages all have the prefix com.adobe.portfolio.

When building a Navigator you normally use these higher-level API packages, and only need to use the lower-level com.adobe.portfolio.api package for a highly customized feature, if at all. Additionally, the classes in the higher-level API are skinnable. Skinning will be covered in the next article.

Adding the “Show next file” and “Show previous file” buttons

Open Main.mxml which is located in the src folder of your Navigator project.

Locate the NavPreview object (around line number 124) and paste the following MXML code sample just above it.

<components:FileNavigationButton navigationType="previous" click="collectionManager.onGotoPreviousAttachment(event)" left="25" top="{innerGroup.height/2}" />
<components:FileNavigationButton navigationType="next" click="collectionManager.onGotoNextAttachment(event)" right="25" top="{innerGroup.height/2}" />

In the Portfolio Framework there is a single FileNavigationButton object that serves both the next and previous functions. The “navigationType” property is required for skinning purposes, it determines the rotation of the arrow in the UI.

Try running the Navigator in the Preview Application by Pressing the Run button in Flash Builder 4. You should see something like the image below. The first time you run the previewer, there won’t be any items in the Portfolio so it will look a little empty but you should be able to clearly see the Previous and Next buttons.

If the Preview application launches but you are not seeing your Navigator, close Flash Builder 4 and restart it running as administrator.

To simulate how your Navigator will behave with a few items in it, open the Quick Test tab in the right hand panel and click Add Multiple. A few “Fake Files” will be added to your simulated Portfolio so you can test the button that you just created. Check the box to Remember Attachments so you won’t need to do this step again.

Now that you’ve tested your Navigator in the Previewer application, you’re now ready to test it in Acrobat X which means you’ll need to create a .NAV or Navigator file. Close the Preview application.

Creating a .NAV file for use in Acrobat X

  1. You must first build the .SWF file that will be embedded in your .NAV file. From the Flash Builder 4 menu select Project -> Export Release Build. Accept the defaults and click Finish. Allow the project to build.
  2. When step one is complete, select File -> Export -> Other
  3. Open the Adobe Navigator category and select either Debug or Release Navigator. Then click the Next button.
  4. Set the destination to a folder on your machine. I prefer saving the .NAV to the desktop to make the import into Acrobat easier. Click the Finish button.

You’ve now got a .NAV file for use in Acrobat X Pro. To create a PDF Portfolio and apply your .NAV file to it follow these steps.

  1. Start Acrobat and do one of the following:
    • In the Welcome Screen, click Create PDF Portfolio.
    • Click the Create button in the upper-left corner of the toolbar, and choose PDF Portfolio from the menu.
    • Choose File > Create > PDF Portfolio.
  2. Click the Import Custom Layout button and select the .NAV file that you just exported.
  3. Click “Add Files” and select a few PDF files or images from your drive. Just about any file type can be added but images and PDF files render thumbnails the fastest so I prefer to use those for testing purposes.

Your PDF Portfolio should open in a few seconds and look pretty much like the one in the image below.

That’s it! You’ve created your first Acrobat X PDF Portfolio layout.

Download the completed Flash Builder 4.5 project

Download the .NAV file.

The next article in this series discusses how to create custom skins or themes for your PDF Portfolios.