Customizing PDF Portfolio Layouts
Part 2: Your First .nav file

The Navigator .nav File Format

Introduction:

In part one of this series, I showed how to create a basic Navigator using Flex and outputting it as 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.

To get a quick overview of the rest of this article, watch this video and then come back here for more detailed and updated information.

A Navigator file collects into a single, special kind of ZIP file, all the resources required by a PDF Portfolio Navigator. The core piece of a Navigator is a .swf file that controls the look and feel of a PDF portfolio. The Navigator file also includes an XML manifest, a mimetype file, metadata 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 part one, 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 extracted from the Navigator file and stored in the PDF Portfolio.

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 with a default Navigator icon. As you can see on the right, a .nav file, on the other hand, contains a required file called "navigator.xml". This file can be used to customize the way that your navigator presents itself in Acrobat.

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.
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, which 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.

The navigator.xml file that I'm using in the example 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.

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. You can see this in context by loading the Flex project linked to at the end of this article.

<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 scripts (.xml) to package up a compiled navigator and its pieces. Because most archiving tools do not let you have very granular control over which files get compressed and the mimetype file in the .NAV must not be compressed, ant scripts 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 3:

Choose Help > Software Updates > Find and Install from the main menu.
In the Install/Update dialog, choose "Search for new features to install".
Check the "Europa Discovery Site" box. Optionally, check the "Automatically select mirrors" box; if you do not you will manually select a mirror site at the next step.
Press "Finish".
In the Updates dialog, open the "Europa Discovery Site" tree node, and open the "Java Development" item by clicking on the plus icon. Do not check the check-box beside the "Java Developement" item as it would require you to install 25 modules when you just require one. Check the check box beside "Eclipse Java Development Tools 3.3.1". Click the next button.
In the Install dialog, read the text of the license agreements, then, assuming you do agree, choose the "I accept the terms in the license agreements" option.
Press "Next".
The Install dialog will show one more wizard page. Press "Finish".
Flex Builder will take several minutes to install the .jar files.
In the Verification dialog, press "Install".
When Flex Builder asks whether it is OK to restart, press "Yes".

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 .nav, you simply context-click on the script and choose the 2nd "Run As" choice for Ant (with ...). Select "build-navs" and press Run. Your new .nav file should show up in the "bin-release/nav" folder. You may need to "refresh" the folder to see it. Once you have the .nav, you can install it into your navigators folder, instructions below.

If you keep your own navigator project folder structure the same as mine, you only need to modify two lines in the script, the project name and the value of the "navName" parameter. These are highlighted in red below.

<?xml version = "1.0" encoding = "ISO-8859-1" ?>
 <project name='PDF_Portfolio_Tutorial_02' basedir='.'>
   <target name="build-navs">
     <antcall target="build-nav">
 	  <param name="navName" value="_02_FirstNAV"/>
 	</antcall>
   </target>
   <target name="build-nav">
     <delete file="bin-release/nav/${navName}.nav" failonerror="true"/>
     <zip destfile="bin-release/nav/${navName}.nav" compress="false">
 	  <!-- ensure mimetype is first -->
         <fileset dir="navResources/${navName}">
           <include name="mimetype"/>
         </fileset>
         <fileset dir="navResources/${navName}">
           <exclude name="mimetype"/>
         </fileset>
     	<fileset dir="bin-release">
           <include name="${navName}.swf"/>
         </fileset>
     </zip>
   </target>
 </project>

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. Open Finder.
2. Browse to this location: /Applications/Adobe Acrobat 9 Pro/Adobe Acrobat Pro
3. Hold the Ctrl key and select the Adobe Acrobat Pro application. Choose Show Package Contents.
4. Browse to this folder location in the Adobe Acrobat Pro application: /Contents/Resources/en.lproj/Navigators
5. Drag the "_01_HelloWorld.swf" file to this location in Finder.
6. Restart Acrobat if it's running.
7. In the "Edit PDF Portfolio" panel you should see an "Other Layouts" category in addition to "Basic Layouts"

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 3.

Files:
The Acrobat 9 ActionScript SDK
The Your First .nav file Project

How To:

Adobe Resources:

External Resources:

About Me: