Guide to Adding Custom Themes and Headers to PDF Portfolio Layout files for Adobe Acrobat X

Background:

Acrobat X PDF Portfolio Layouts (Navigators) can have a variety of "looks" applied to them called "Visual Themes" in the Acrobat User Interface or "Skins", if you are reading the Adobe Acrobat Portfolio SDK documentation. For the purposes of this document, Skins and Visual Themes will be use inter-changeably.

To use a custom theme, click Import Custom Theme. Navigate to the custom theme on your computer and open it. The theme is immediately applied to your Portfolio and appears in the Visual Themes list as "Custom". Unlike custom layouts, custom themes are only applied to the current PDF Portfolio and are not permanently added to the Visual Themes panel. Themes are created in Adobe Flash Professional or Adobe Flash Builder and have a .swf extension.

Adobe Acrobat X supplies several built in Header layouts for PDF Portfolios but headers can also be created manually. Manually created headers can be saved into the current PDF Portfolio but are not persistent in the PDF Portfolio Layout file.

Note: This document assumes that the only thing you want to do is add your own custom themes to the default Adobe PDF Portfolio Layout files that are shipped with Adobe Acrobat X and suggests a method of making custom themes and headers persistent.

Tools You’ll Need

A ZIP compatible archiving tool – PDF Portfolio Layout files (.nav) are ZIP archives with a few very specific details about them. The one detail that is of interest for this article is the fact that a file called “mimetype” must be the first file in the archive and must be uncompressed. There may be others, but I have only found two tools that work for this use case, WinZip on Windows and Springy on the Mac.  

An XML Editing tool – The files that we are going to edit are XML, you’ll need a very basic understanding of XML but an editing tool with decent syntax highlighting will help. I use Adobe Dreamweaver but anything will work.

You can also do everything I discuss in this document using Flash Builder 4. If you are already using the Adobe Acrobat Portfolio SDK in Flash Builder 4 for developing custom layouts, that’s probably the better option.

General rules for modifying a .nav file

The remainder of this document describes editing files, creating folders and adding images to the .nav file. While .nav files are basically .zip files, do not decompress the archive. There are some very specific rules about how the archive is constructed (mentioned above) so it’s easier if you open the .nav files with your archive tool, either WinZip (Windows) or Springy (Mac) and work within the archive.

Getting Started

  1. Make a backup of all of the .nav files from the Acrobat X navigators folder and store them in a safe place. Folder paths are below.
    Windows:
    C:\Program Files\Adobe\Acrobat 10.0\Acrobat\Navigators
    Mac:
    /Applications/Adobe Acrobat X Pro/Adobe Acrobat Pro.app/Contents/Resources/Navs
  2. Place a copy of the .nav files in your personal data folder located at the folder below

    Windows XP:
    %USERPROFILE%\Application Data\Adobe\Acrobat\10.0\Navigators
    Windows 7:
    %USERPROFILE%\\AppData\Roaming\Adobe\Acrobat\10.0\Navigators
    Mac:
    /Users/USERNAME/Library/Application Support/Adobe/Acrobat/10.0/Navigators

  3. Open the .nav file using your archive tool
  4. Open the “navigator.xml” file in the root of the archive and change the “id” attribute of the “navigator” element. Prefix the value with “urn:” so the value might be “urn:MyClickThrough”. Each .nav file must have a unique id.
  5. Save and close the “navigator.xml” file and allow the archive tool to update the archive.

Optional steps

  1. Open the “strings” folder and navigate to the folder for your local language and open that.
  2. Open the “strings.asfx” file in your XML editor.
  3. Edit the name of your .nav file. Modify the text between the val tags. This is the name that will appear in the Acrobat UI.

    
    	My Navigator Name
    
    
  4. Save and close the “strings.asfx” file and allow the archive tool to update the archive.

The remainder of the work described in this document will bedone to these new files.

Adding a Custom Theme to a PDF Portfolio Layout File

Unlike Custom Layouts, when you “Import a Custom Theme” through the Acrobat UI, it is only applied to the current PDF Portfolio and not permanently added to the Visual Themes panel. For this reason, you may decide that you want to add your Custom Theme to the .nav files that come with Adobe Acrobat and any custom layouts that you may have developed. By modifying a few XML files and adding the .SWF for your Custom Theme to the .nav file, you can make your custom theme appear in the Visual Themes panel permanently.

General Steps to Add a Custom Theme to an Existing PDF Portfolio Layout File

  1. Add the .swf skin file to the .nav file and modify the properties.xml file in the .nav file to reference your skin file.
  2. Add a background image file to the .nav file and modify the properties.xml file to reference your background image.
  3. Create a header.xml file for your custom header, add the header.xml file to the .nav file and modify the properties.xml file to reference your header file.

Step 1: Adding the .swf skin file to the .nav file.

  1. Open the .nav file with your archive tool.
  2. Open the “navigator” folder.
  3. Optional: If you want to remove all of the default Adobe theme files, delete the images and .swf files from the “navigator” folder.
  4. Add your theme’s .swf file to the “navigator” folder.
  5. Open the “properties.xml” file located in the “navigator” folder.
  6. Locate the “PropertyList” element with the name "skins"
  7. Optional: If you want to remove all of the references to the default Adobe themes, delete all of the “SkinBinary” elements and their content.
  8. Copy the “Theme XML” snippet below and paste it under the “PropertyList” element with the name "skins". Edit the attributes in red to the values that you need. The url reference to your theme’s .swf file is case sensitive. The values for the imageScale and imagePosition are explained later in this document. The value of imageSource will be used in the next few steps. If you are not using a background with your theme, remove the line referencing imageSource.
  9. Do this for each theme you have
  10. In the “PropertyList” element with the name "skins", set the “active” attribute value to be the same as the “name” value of the theme you want to be the default when your layout is applied to a PDF Portfolio.
  11. Save and close the “properties.xml” file.
  12. Save and close the archive.

Your theme will now appear in the “Visual Themes” panel of the Acrobat X UI when you import your updated layout.

Theme XML:

<SkinBinary name="yourTheme" labelKey="yourTheme" label="Your Theme" url="navigator/YOUR.swf" type="flash">  <SelectEffect type="propertyValue" context="com.adobe.navigator.background" property="imageScale" value="noBorder" />
     <SelectEffect type="propertyValue" context="com.adobe.navigator.background" property="imageOpacity" value="100" />
     <SelectEffect type="propertyValue" context="com.adobe.navigator.background" property="imageSource" value="your_background" />
     <SelectEffect type="propertyValue" context="com.adobe.navigator.background" property="imagePosition" value="bottomRight" />
</SkinBinary>

Adding a Default Background Image to a PDF Portfolio Layout File

There are two "layout" properties which define how the background image will appear in the PDF Portfolio window. The first layout property is the scale property. See Table 1: Background Scale Property Values for an explanation of these properties. The second layout property is the position property. Other properties that affect the appearance of the background are opacity and blur. Opacity (alpha value) determines how transparent the object is and blur gives the backdrop a depth of field effect.

Images supported

The source files for images can be JPEG, progressive JPEG, unanimated GIF, or PNG files.

Note: If you use an animated GIF file, only the first frame is displayed.

Background images can be added independently of a Custom Theme and will appear in the “Background Image” drop-down list of the “Background” panel.

Table 1: Background Scale Property Values

Value

Effect

actualSize

Actual size entered images are displayed at their full resolution (i.e. not scaled) and positioned based on the position property. If the image is larger than the window than it is clipped.

actualSizeTiled

Tiled images are displayed at their full resolution (i.e. not scaled) with the anchor image at the center of the containing window (if center position was chosen). Images are tiled (repeated) from the anchor image to the left, right, top and bottom until the entire containing window is filled with the original image.

showAll

Images displayed with the “show all" layout are scaled to fill the containing window without clipping on the top, bottom or sides. If the containing window is not the same aspect ratio as the image, the image fills the window in one dimension and has borders in the other dimension. Resizing the containing window causes the image to rescale to the new size.

noBorder

Images displayed with the "scaled no border" layout are scaled to fill the containing window, but clipping may occur on the top and bottom or sides. If the containing window is not the same aspect ratio as the image, the image fills the window in one dimension and be clipped in the other dimension. Resizing the containing window causes the image to rescale to the new size.

Position Property Values

The Position Property Values are listed below and position the background image where they say they do.

  • topLeft
  • topCenter
  • topRight
  • middleLeft
  • center
  • middleRight
  • bottomLeft
  • bottomCenter
  • bottomRight

Step 2: Add a background image file to the .nav file

  1. If the archive is not already open, open the .nav file with your archive tool.
  2. Open the “navigator” folder.
  3. Add your background image file to the “navigator” folder.
  4. Open the “properties.xml” file located in the “navigator” folder.
  5. Locate the PropertyContext element with the name "background" and it’s child element “PropertyList” with the name "imageSource".
  6. Copy the “Background XML” text below and paste it as a new child to the element above.
  7. Set the property of the “active” attribute of the PropertyContext element with the name "background" to be the same value as the “name” of background you want to be the default.
  8. Save and close the “properties.xml” file.
  9. Save and close the archive.

The name of your background image will now appear in the”Background” panel of the Acrobat X UI.

Background XML:

<PropertyBinary name="your_background" labelKey="yourDefault" label="Your Default Image" url="navigator/your_background.png"/>

Adding a Default Header to a PDF Portfolio Layout File

A default header can be added to your PDF Portfolio automatically by adding a “header.xml” file to the “navigator” directory of the archive. The header is a series of “CanvasItem” elements. For the PDF Portfolio Layouts that ship with Acrobat X, the header is always 100 pixels high, if present. Because the header is designed to fit within the available width of the PDF Portfolio window, the width of each CanvasItem is determined by the padding to the left and right of the object. You can also add padding to the top and bottom but because the height is fixed, the height of the object is predictable.

Headers are tied to the PDF Portfolio Layout, not the Visual Theme. If you add a custom header, it will persist when you change themes but not layouts.

Note: There is currently no specification for the “header.xml” file but the example below provides some guidance to creating your own custom header files.

You can also add additional header templates to the “properties.xml” file and these will show up in the Acrobat X UI. Header templates create placeholders at specific locations for images and text, they do not populate these objects with content as the “header.xml” file does. See Step 3 for instructions.

Text Alignment

The Acrobat UI does not allow for left or right alignment of text; text added through the Acrobat UI will always be horizontally and vertically centered within the text box. However, the header.xml file does support textAlign values of “left”, “right” and “center” in the “p” element. Vertical alignment can be set by adding a “verticalAlign” property to the “TextFlow” element, values can be “top”, “bottom” and “middle”.

Storing Images

When authoring your header through the Acrobat X UI, Acrobat stores images in the “navigator/canvas_images” directory in the archive. You are not required to use this directory but it is the convention in Acrobat X and is encouraged. As long as the path to the image is relative to the root of the archive and under the “navigator” folder, “navigator/myImages/my Header/logo.jpg” for example, any path will work.

Limitations

Currently, in the PDF Portfolio Layouts that ship with Adobe Acrobat X, only static images and text are supported. HTML text with links, .swf files and animated .gif files are not supported.

Step 3: Create a header.xml file for your custom header and add the header.xml file to the .nav file

If the archive is not already open, open the .nav file with your archive tool.

  1. Open the “navigator” folder.
  2. Add your header.xml file to the “navigator” folder.
  3. Open the “properties.xml” file located in the “navigator” folder.
  4. Locate the PropertyContext element with the labelKey "headerProperties" and it’s child element “PropertyList” with the name "presetList".
  5. Add a new CanvasTemplate element to the list that’s there. Your CanvasTemplate should match the header.xml file if you have one, otherwise your template will be just placeholders. Note: The CanvasTemplate below matches the header.xml file that follows.
  6. Save and close the “properties.xml” file.
  7. Save and close the archive.

CanvasTemplate XML

<CanvasTemplate name="adobeHeaderNarrow" labelKey="adobeHeader" label="Adobe Header 1024x768">
     <CanvasItem type="image" width="100" right="0" top="0" bottom="0"/>
     <CanvasItem type="text" left="15" width="515" top="0" bottom="0"/>
     <CanvasItem type="text"  width="140" top="0" bottom="0" right="100" />
</CanvasTemplate>

Examples: