If you're seeing something other than Verdana, the Font is Graublau Sans Web by FDI fonts.info

Creating Custom PDF Portfolio Layouts
Updated 11/13/2009

Part 1: Your First .NAV file

Introduction:

In the Bootstrapping article of this series, I showed how to create a basic Navigator using Flex and compiling it to a .SWF file. Acrobat can use any .SWF file that implements the Acrobat INavigator interface as a Navigator but you may not always want to embedd all of the assets that your Navigator needs into the .SWF file. Additionally, you may want to add your Navigator to a specific category of Navigators or otherwise customize how your Navigator is presented in the Acrobat User Interface (UI).For this, you'll need to wrap your .SWF file in a Navigator (.NAV) file.

A Navigator file collects into a single, special kind of ZIP file, all the resources required by a Navigator. The core piece of a Navigator is the .SWF file that controls the look and feel of the PDF portfolio. The Navigator file also includes a mimetype file, an XML manifest and other auxiliary resources required by the .SWF file, such as images and fonts, localized strings, and other private data.

Just like the .SWF we used in the previous article, Acrobat loads Navigators from two standard directories. One at the application level and one in the user folder. When a user chooses a Navigator for a portfolio, the necessary information is copied from the Navigator file and stored in the PDF file.

The difference between using a .SWF versus using a .NAV is illustrated in the images below. The image on the left shows how the "Hello World" example from part one, a simple .SWF file, presents itself in the Acrobat UI. SWF files will always be listed in the "Other Layouts" category and show a default Navigator icon. As you can see on the right, images and strings in a .NAV file can be used to customize the way that your Navigator presents itself in the Acrobat UI.

The Navigator Component files:

As a minimum, a Navigator file needs to contain an uncompressed file named "mimetype", a file named "Navigator.xml", and a Navigator .SWF file. You can also have an icon file, a locales file, one or more strings files, and other resources required by your Navigator. Below is a brief overview of the Navigator component files, detailed information on each of the component files is available in The Acrobat 9 ActionScript SDK

mimetype file	A file called "mimetype" must be the first file stored in the .NAV file. It must be uncompressed, and its contents must be the string "application/vnd.adobe.pdf-Navigator". Because some tools, like the compressed folder functionality built into Windows Explorer don't let you control compression, the easiest way to get started on your own Navigator is to copy an existing one that already has this file.You'll find a .NAV attached to the example project at the end of this article. However, my recommendation is that you use Ant tasks to compile the .NAV as I explain below.
Navigator.xml file	The "Navigator.xml file" is the starting point for Acrobat to begin processing a Navigator file. It contains basic information about the Navigator that allows Acrobat to describe the Navigator to the user interface without loading the Navigator .SWF file.
SWF file	The Navigator .SWF file manages the display of a portfolio's contents. A Navigator .SWF file may refer to resources using URLs. However, only relative URLs may be used to reference other files in the Navigator. The code example below will make this a little clearer.
Icon file	The icon file is a small image used to visually represent the Navigator in the user interface. PNG is the recommended format for this icon but JPEG will work too. The recommended size is 42 x 42 pixels.
Locales file	The <locales> element and child <locale> elements may be present in the Navigator.xml file or in a separate locales file. If the <locales> element is not present, Acrobat assumes the Navigator is localized for Acrobat's current locale. It is strongly recommended that the Navigator locale be explicitly specified. This allows Acrobat to distinguish between two Navigators that have the same Navigator ID but are localized for different locales.
Strings file	A strings file is an XML file that associates string IDs with localized strings.
Resource files	The Navigator .SWF file can refer to other files. Any files other than types that are not allowed as PDF file attachments can be included and referred to by the Navigator, including images, video, and text files.

An example Navigator.xml file is below. If you are familiar with other XML-based formats, you can probably see how the name, category, description and a reference to the icon file are set.

<?xml version="1.0" encoding="UTF-8"?>
  <Navigator src="_02_FirstNAV.SWF" id="Demo" version="1.00" loadAs="module" apiVersion="0.1">
  <name sID="navName">My First Navigator</name>
  <category sID="navCategory">Custom</category>
  <description sID="navDescription">Just an example</description>
  <icon src="icon.png"/>
</Navigator>

More details for each element can be found in The Acrobat 9 ActionScript SDK Documentation.

Note: The project file for these tutorials uses a localizable strings file so it will look considerably different from the example above. To change the name, category and description in the tutorial project, edit the "strings.asfx" file.

When I'm writing the code for my Navigators, I like to do all of my work in Flex Builder so I installed XMLBuddy so that I can modify my Navigator.xml file right inside of Flex but you can use anything you like.

One thing to point out is that the "id" and "version" should be set with care. Each .NAV file needs to have a unique id. You can have two files with different names in the Navigators folder but if they have the same "id" only the last one to load will be available. Additionally, the version number can be used to alert users that a Navigator that they have installed on their system is a newer version of the one that is embedded in the PDF Portfolio that they are looking at. In the graphic to the right, the PDF Portfolio is using version 1.0 of the example Navigator and that version is embedded in the PDF. But Acrobat has version 1.5 of a Navigator with the same "id" in it's Navigator folder. When this happens, the word "New" appears beside the newer version of the Navigator and the user can easily update the PDF Portfolio with the newer Navigator.

Using Resource Files:

As mentioned earlier in this article, your Navigator can use resources that are stored in the .NAV file. These files must be stored in a folder called "Navigator" in the root of the .NAV file. You can reference these files from your .SWF application through URLs as in the example code below.

<mx:Image source="Navigator/ActionScriptHeader.png"/>

Packaging your .SWF file and its resources into a .NAV file

Again, I like to do all of my Navigator work in Flex Builder so rather than use something like WinZIP. You can use Ant tasks to package up the .SWF and the rest of the files required for the Navigator. Because the mimetype file must be the first file in the .NAV and must not be compressed, Ant tasks may be one of the easiest and least error prone ways of creating your .NAV file.

You need to install the Java Development tools into Eclipse to get Ant.

How to install Eclipse Java Development Tools in Flex Builder 4:

1. Choose Help > Install New Software.
2. Add the "Galileo" site with the URL http://download.eclipse.org/releases/galileo/
3. When the list box populates, open "Programming Languages".
4. Check "Eclipse Java development tools".
5. Finish the Wizard.

Building your .NAV file with Ant.

The example project linked to at the end of this article includes a "build.xml" file that you can copy and edit. The script points to the folders in the project containing the pieces that need to be collected into the final zipped .NAV file. To build the .NAVs, you simply context-click on the "build.xml" file and choose "Run As" then "Ant Build". Your new .NAV file should show up in the "bin-release/nav" folder.

Conclusion:

Now that I've shown you how to connect your code to the Acrobat API and how to bundle everything up into a nice, pretty .NAV file, we can start making this Navigator actually do something interesting in Part 2.

After downloading this example and compiling the code, you can install the Navigator by following these simple steps.

Installation:

Windows:

1. From Windows, select "Start" then "Run". Paste the following line into the text box and press enter
   
   %USERPROFILE%\Application Data\Adobe\Acrobat\9.0\
   
   
2. Create a directory called "Navigators" if you don't already have one
3. Drag the "_01_HelloWorld.swf" file to the "Navigators" directory
4. Restart Acrobat if it's running.
5. In the "Edit PDF Portfolio" panel you should see an "Other Layouts" category in addition to "Basic Layouts"

OSX:

1. Browse to /Application Support/Adobe/Acrobat/9.0_x86 in your user Library folder
2. Create a directory called "Navigators" if you don't already have one
3. Drag the "_01_HelloWorld.swf" file to this location in Finder.
4. Restart Acrobat if it's running.
5. In the "Edit PDF Portfolio" panel you should see an "Other Layouts" category in addition to "Basic Layouts"

Files:
Download Source

Comments: