Working with the Portfolio Collection Fields

Introduction:

The focus of this article is to show you how to add the necessary code to your navigator to display and edit the metadata for items in a PDF Portfolio.One important fact to point out is that there can be XMP metadata attached to any object in a PDF file though there is no user interface to see it other than the document XMP and XMP associated with images.The pictures below show the document XMP metadata for a PDF file.This information is also stored in the "info" dictionary of a PDF file.

The XMP matadata is not the kind of metadata that this article discusses. In the Acrobat SDK, a PDF Portfolio is referd to as a collection and the files in the portfolio are an array of dataObjects. The collection fields are the metadata fields and associated content that belongs to the collection. That's the information you see when you look at a PDF Portfolio in the list view, as you can see below. The reason I bring this up is the fact that the ActionScript API does not have assess to the XMP metadata in a PDF file.

Working with the Standard Portfolio Collection Fields

In Part 3 of this series, I discussed using the "fileName" and "isOpen" properties of an IAttachment. As a reminder, the dataSource for the DataGrid in the example was the currentItems object which is bound to the set of items in the current folder of the PDF Portfolio. Because of this, I could set the dataField for column one to be the "fileName" property and the file name of the item will then show up in the column. I also created a label function that used the "isOpen" property to calculate a label for the second column.

	<mx:DataGrid id="itemList" initialize="onInitialize()" dataProvider="{currentItems}" 
		width="350" 
		rowCount="12" doubleClickEnabled="true" 
		itemDoubleClick="itemDoubleClicked(event)">
		<mx:columns>
			<mx:DataGridColumn dataField="fileName" headerText="Name"/>
			<mx:DataGridColumn labelFunction="isItOpen" headerText="File Opened"/>
		</mx:columns>
	</mx:DataGrid>

There are other usefull string, date, and uint properties that might be useful in your navigator. Additionally, you can get and set the values of your own custom fields using getFieldValue() and setFieldValue() which I'll discuss a little further down in this article. In the "_05_WorkingWithMetadata" sample project, I added two additional columns to the DataGrid that I've been working with; the "Description" and the 'Title" columns. I'd like users to be able to modify the title and description of any item in the PDF Portfolio so I also made a few other changes to the DataGrid properties which you'll want to look at in the sample code, the most significant one's being that I set the DataGrid to "editable" and set a function for the "itemEditEnd" event.

Like the "fileName" property, the "description" property is standard property of an IAttachment except that it's read/write so it's pretty easy to use. You just set the item's "description" property to a new value and that's it. Below is a complete list of all the IAttachment properties you can use in this way.

Properties of an IAttachment:

Working with Custom Portfolio Collection Fields

The Acrobat ActionScript API does not allow custom portfolio collection fields to be added to or removed from a PDF Portfolio. However, the "navigator.xml" file that is part of your .nav file can be used to add custom fields to the portfolio. The "initialFields" element is used to both add new custom fields, "Title" in the case below, and define the set of fields visible when looking at the PDF Portfolio in the list view as well as their order. You can also use "sID" attributes to localize the "name" that shows up in the detail view column heading.

	<initialFields>
		<field name="Name" type="filename"/>
		<field name="Title" type="text" editable="true"/>
		<field name="Description" type="desc" editable="true"/>
	</initialFields>

Note: These custom fields will be added to the PDF Portfolio when the user selects your layout even if they switch to another layout and do not save your layout to that PDF Portfolio.They cannot be programatically removed using the Acrobat ActionScript API once added.The JavaScript API can be used to remove collection fields or they can be removed through the Acrobat User Interface.

With the custom field now available in the PDF Portfolio, you can use getFieldValue() and setFieldValue() to get and set the value of the field.

Files:
The Acrobat 9 ActionScript SDK
Working with the Portfolio Collection Fields Project