Interacting with the Portfolio Properties Panel

This article is part four of a series and builds on exercises and concepts presented in parts one through three. If you have not already read the first three parts in this series, set up the Acrobat X Portfolio SDK and successfully built the MyCustomTheme project, please stop reading this article now and go to the Your First Navigator Project article.

Background:

One of the great new benefits of the Acrobat X Portfolio SDK over the Acrobat 9 Portfolio SDK is the ability to create custom panels in the Acrobat UI to control properties of your Portfolio Layout (navigator). Previously, you had to put UI elements that were specific to your layout on the layout itself, not a very good solution. The images below represent the default panels and a custom panel used by the Billboard layout.

Default Panel   Custom Panel

The custom panels are created by Acrobat when it reads the properties.xml file inside your .nav file when your layout is selected. You’ve already had experience with the properties.xml file in the previous two articles. Acrobat creates the panel based on XML code in the properties.xml file then triggers events when one of the items changes. The Portfolio API can then be used to respond to these events. In the example below, we’re going to create a slider that will alow you to adjust the height of the Portfolio header area.

Adding a Custom Properties Panel to a PDF Portfolio Layout

  1. Open the MyCustomTheme project that you completed in the previous article.
  2. Open the properties.xml file from the navfiles\navigator folder.
  3. Add the following XML snippet to the end of the file just before the </NavProperties> tag.
    <PropertyContext label="My Properties" uid="com.my.properties" global="true">
    <PropertyNumber name="headerHeight" label="Header Height" minValue="50" value="100" maxValue="250"/>
    </PropertyContext>

    This code will add a tab to the default right-hand panel called My Properties. We’ll be able to refer to it by it’s uid, this will make more sense when you see the associated ActionScript. The global property determines if this panel is always visible or if it is only visible within a specific context. You’ll notice that when you are editing a Portfolio header area, the Header panel becomes visible, this is because you are in the header context.

    A PropertyNumber element will create a slider labeled Header Height with a minimum value of 50, a maximum value of 250 and a default of 100. The variable name when we use it in ActionScript will be headerHeight.

  4. Preview the project by pressing Run in Flash Builder. Be sure to set the environment to Authoring Mode. Open the Properties panel, you should see a tab called My Properties. You can move the slider back and forth but it’s not hooked up to anything yet. That’s what we’ll do in the next few steps.
  5. Download CustomProperties.as and add it to the src folder of your project. This code will allow your custom properties to be read and written just like the default ones without you needing to do any of the work, the Portfolio SDK Framework takes care of all of the event handling.
  6. Open Main.mxml.
  7. Copy the ActionScript snippet from below and past it somewhere within your script tag.
    import com.adobe.portfolio.managers.PropertyManager;
    private var _propertiesFactory:ClassFactory;
        override public function get propertiesFactory():ClassFactory
        {
        if (_propertiesFactory == null) {
        _propertiesFactory = new ClassFactory(CustomProperties);
        }
        return _propertiesFactory;
        }
  8. Locate the components:Header object and replace it with the mxml snippet below. This will bind the height of the Portfolio header to the value of headerHeight slider.
    <components:Header id="header" width="100%" top="0" heightIfPresent="{(PropertyManager.instance.commonProperties as CustomProperties).headerHeight.numValue}"/>
  9. Preview the project by pressing Run in Flash Builder. Be sure to set the environment to Authoring Mode. This time, the slider works and you can see the layout dynamically update.

That’s the basics. Now let’s add a footer to the layout just to demonstrate the various types of properties you can set through the panel. You can add text fields, color pickers, drop-down list boxes, check boxes and buttons. I’ll discuss buttons in a future article; for now I’ll just deal with the first four that I listed.

  1. With Main.mxml still open, add the following label object just below the two FileNavigationButton components
    <s:Label width="100%" bottom="{miniNav.height}" fontSize="24" paddingLeft="10" paddingRight="10" paddingBottom="10"   
    text="{(PropertyManager.instance.commonProperties as CustomProperties).widgetText.stringValue}"
    color="{uint((PropertyManager.instance.commonProperties as CustomProperties).widgetTextColor.numValue)}"
    textAlign="{(PropertyManager.instance.commonProperties as CustomProperties).widgetLocation.activeValue.value as String}"
    visible="{(PropertyManager.instance.commonProperties as CustomProperties).showWidget.booleanValue as Boolean}"
    />
  2. Open the properties.xml file
  3. Replace PropertyContext section that you added in step 3 above with the the following XML snippet. The
    CustomProperties.as you added in step 5 is already set up to handle these additional properties.

    <PropertyContext label="My Properties" uid="com.my.properties" global="true">
    <PropertyNumber name="headerHeight" label="Header Height" minValue="50" value="100" maxValue="250"/>
    <PropertyString name="widgetText" label="Widget Text" value="Enter some text"/>
    <PropertyColor name="widgetTextColor" label="Widget Text Color" value="0x000000"/>
    <PropertyList name="widgetLocation" label="Widget Location" active="left">
    <PropertyString name="left" label="Left" value="left"/>
    <PropertyString name="center" label="Center" value="center"/>
    <PropertyString name="right" label="Right" value="right"/>
    </PropertyList>
    <PropertyBoolean name="showWidget" label="Show Widget" description="Show the Widget" value="true"/>
    </PropertyContext>
  4. Preview the project by pressing Run in Flash Builder. Be sure to set the environment to Authoring Mode. Open the Properties panel, you should see a tab called My Properties similar to the one below. You should be able to modify the properties from the panel and immediately see the effect.

And that’s how you can add a custom properties panel to a PDF Portfolio Layout. As I mentioned earlier, you can also add buttons to the properties panel which trigger events in the Portfolio Layout but I’ll cover that in the "Reading and Writing Resources and Persistent Data" article coming soon.

Download the completed Flash Builder 4.5 project
Download the .NAV file.