Packagecom.adobe.portfolio.api
Interfacepublic interface ICollection extends flash.events.IEventDispatcher

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

An interface that represents a PDF collection or Portfolio.



Public Properties
 PropertyDefined By
  decorateFields : Boolean
A PDF document can have schema fields with generic metadata types like text, date, or number.
ICollection
  embeddedFontList : Array
[read-only] Returns an array describing the fonts embedded in the portfolio.
ICollection
  embedFontsOnSave : Boolean
Get/set the boolean flag indicating whether or not registered fonts should be embedded when the document is saved.
ICollection
  fields : Array
An ordered array of IField instances.
ICollection
  fileName : String
[read-only] The file name of the collection, not including the path.
ICollection
  items : IList
[read-only] An ordered list of non-null IAttachment instances.
ICollection
  locale : String
[read-only] Gets the locale for this collection's resources.
ICollection
  permissions : IPermissions
[read-only] Represents the set of permissions for this portfolio.
ICollection
  sort : Array
An ordered array of ISort instances.
ICollection
Public Methods
 MethodDefined By
  
addFiles(response:Function = null):void
Launches a file import dialog for the purpose of importing a file or group of files from the host file system to the package.
ICollection
  
addFolder(response:Function = null):void
Launches a folder import dialog for the purpose of recursively importing a folder structure from the host file system into the package.
ICollection
  
addResource(browseDialogTitle:String, browseDialogFilters:Array, relativeURL:String, response:Function = null):void
Adds custom resources needed by the navigators.
ICollection
  
createFolder(name:String, response:Function = null):void
Create a new folder in the current folder.
ICollection
  
deleteItems(attachments:Array, response:Function = null):void
Deletes the specified attachments.
ICollection
  
deleteResource(relativeURL:String, response:Function = null):void
Deletes the resource associated with the path.
ICollection
  
getDirty(response:Function):void
Returns the 'dirty' status of the ICollection.
ICollection
  
getLocalizedString(key:String, defaultValue:String = null):String
Gets a localized string from the navigator's resources contained in the collection.
ICollection
  
getSessionData(key:String, callback:Function):void
Returns session data for the specified key.
ICollection
  
getSessionDataKeys(callback:Function):void
Returns keys for all session data associated with this collection.
ICollection
  
registerFonts(fonts:Array):void
Registers an array of fonts that should be embedded by the host application.
ICollection
  
reorderFiles(attachments:Array):void
Changes the order of a set of IAttachments.
ICollection
  
resolvePath(relativeURL:String):String
Given a relative path to a resource, return a URL from which the resource can be loaded.
ICollection
  
setDirty():void
Sets the flag indicating that the ICollection is dirty and needs to be saved.
ICollection
  
setSessionData(key:String, sessionData:*):void
Stores session data under the specified key.
ICollection
  
writeResource(buffer:ByteArray, relativeURL:String, response:Function = null):void
Replaces the contents of the navigator custom resource if one exists for the given path or creates a new one otherwise.
ICollection
Events
 Event Summary Defined By
  This event is dispatched when the navigator should write out any pending data.ICollection
  This event is dispatched when session data changes.ICollection
Property Detail
decorateFieldsproperty
decorateFields:Boolean

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

A PDF document can have schema fields with generic metadata types like text, date, or number. An ICollection schema always includes these fields; additionally, it can have schema fields that map to properties of an embedded file, such as the file's name, creation date, modified date, etc.

When the decorateFieldsproperty is true, the following set of IField instances is included in the collection's fields property, in the given order:

NameTypeEditableVisible
"FileName"FieldType.FILE_NAMEtruetrue
"Description"FieldType.DESCRIPTIONtruetrue
"ModDate"FieldType.MOD_DATEfalsetrue
"Size"FieldType.SIZEfalsetrue
"CompressedSize"FieldType.COMPRESSED_SIZEfalsetrue
"CreationDate"FieldType.CREATION_DATEfalsefalse

The displayName for each field varies with Acrobat's current runtime locale. When this property is false and the navigator sets it to true, the standard fields are prepended to any fields that already exist. All of these standard fields map to attachment properties whose values are always stored in the PDF document, regardless of the document's collection schema. When this property is set to true, Acrobat does not permanently add these fields to the PDF document's schema. The document is not dirtied.

The default value is true.

This property can be used as the source for data binding.


Implementation
    public function get decorateFields():Boolean
    public function set decorateFields(value:Boolean):void

See also

embeddedFontListproperty 
embeddedFontList:Array  [read-only]

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Returns an array describing the fonts embedded in the portfolio. Each entry in the array is an Object which contains the following attributes:

AttributeDescription
fontNameName of the font
fontWeight"normal" or "bold"
fontPosture"normal" or "italic"|
familyNameFamily name of the font, for example, "Adobe Caslon Pro Italic" would have the family name "Adobe Caslon"
styleNameStyle name of the font, for example, "Adobe Caslon Pro Italic" would have the family name "Italic"
psNamePostScript name of the font, for example, "Adobe Caslon Pro Italic" has the PostScript name "ACaslonPro-Italic"

This property can be used as the source for data binding.


Implementation
    public function get embeddedFontList():Array
embedFontsOnSaveproperty 
embedFontsOnSave:Boolean

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Get/set the boolean flag indicating whether or not registered fonts should be embedded when the document is saved.

This property can be used as the source for data binding.


Implementation
    public function get embedFontsOnSave():Boolean
    public function set embedFontsOnSave(value:Boolean):void

See also

fieldsproperty 
fields:Array

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

An ordered array of IField instances.

The description for this API sometimes refers to the fields property as the "schema fields" or "schema" of the ICollection.

The array may be empty but can never be null.

This property may only be set when the permission "Document"/"Modify" has been granted.

The returned array is always a copy of the array contained by the ICollection instances. Modifications to this array copy have no effect on the ICollection.

There are restrictions on the array when setting this property:

Typical usage is to get the existing fields array, optionally rearrange the entries, optionally modify IField instances by calling setters, and set the property to this modified array.

This property can be used as the source for data binding.


Implementation
    public function get fields():Array
    public function set fields(value:Array):void

Throws
Error — An Error is thrown if the array violates any of the rules described above.

See also

fileNameproperty 
fileName:String  [read-only]

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

The file name of the collection, not including the path.

This property can be used as the source for data binding.


Implementation
    public function get fileName():String
itemsproperty 
items:IList  [read-only]

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

An ordered list of non-null IAttachment instances.

The IList may be empty but will never be null. The IList is read-only; attempts to modify it will generate exceptions.


Implementation
    public function get items():IList

See also

IAttachment
mx.collections.IList
localeproperty 
locale:String  [read-only]

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Gets the locale for this collection's resources.

The locale is given as an ISO language and region code. For example, "en_US".


Implementation
    public function get locale():String
permissionsproperty 
permissions:IPermissions  [read-only]

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Represents the set of permissions for this portfolio.

If a function or read-write property in this interface has a dependency on the permissions property, it is explicitly noted in the description of that function or property. An Error is thrown while calling any function or setting any read-write property when the value of permissions disallows it.

This property can be used as the source for data binding.


Implementation
    public function get permissions():IPermissions
sortproperty 
sort:Array

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

An ordered array of ISort instances. Lower-indexed records are higher in sort priority. The INavigatorHost instance's getter always returns a copy.

When changing the sort order, the INavigator implementation is free to reuse existing ISort instances, or create new ones.

When the sort order changes, it may invalidate Acrobat's current settings for the next and previous IAttachment instances. If so, the INavigator instance must notify the INavigatorHost by calling INavigatorHost.setNextPrevious().

This property may only be set when the permission "Document"/"Modify" has been granted.

This property can be used as the source for data binding.


Implementation
    public function get sort():Array
    public function set sort(value:Array):void

Throws
Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

See also

Method Detail
addFiles()method
public function addFiles(response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Launches a file import dialog for the purpose of importing a file or group of files from the host file system to the package. Files are added to the current folder.

This operation is only allowed when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have been granted.

The method accepts an optional callback function as an argument. The callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response:Object parameter contains properties that define the response. These include:

PropertyTypeValue
successBooleantrue if the operation succeeded; false otherwise

Parameters

response:Function (default = null) — Optional notification function, as described above.


Throws
Error — Throws an Error if called when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have not been granted.

See also

addFolder()method 
public function addFolder(response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Launches a folder import dialog for the purpose of recursively importing a folder structure from the host file system into the package. The new folder structure is added to the current folder. All files and folders are added to the package with the same name they have in the file system.

This operation is only allowed when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have been granted.

The method accepts an optional callback function as an argument. The callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response:Object parameter contains properties that define the response. These include:

PropertyTypeValue
successBooleantrue if the operation succeeded; false otherwise.

Parameters

response:Function (default = null) — Optional notification function, as described above.


Throws
Error — Throws an Error if called when the permissions "EmbeddedFile"/"Import" and "EmbeddedFile"/"Create" have not been granted.

See also

addResource()method 
public function addResource(browseDialogTitle:String, browseDialogFilters:Array, relativeURL:String, response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Adds custom resources needed by the navigators. It brings up a file browsing dialog prompting the user to select the needed file. Types that are not blacklisted will be added to the resources.

The data can later be accessed calling loadURL().

This operation is only allowed when the permission "Document"/"Modify" has been granted.

It accepts an optional callback function as an argument. When it is non-null, the callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response parameter contains properties that describe the response. These include:

PropertyTypeValue
'success'Booleantrue if the operation succeeded; false otherwise
'relativeURL'StringThe path that identifes the resource. This is the full relative path to the resource, and may differ from originalURL if the caller passes an incomplete path, which is then completed by addResource(). Use this url to later read the resource.
'originalURL'StringThe path under which this resource was requested. It will match relativeURL except in the case where addResource() has completed an incomplete URL.
'error'StringA non-human-readable String describing the error. It is non-null only if success is false.

Can URLs have "/../" in them? If so, what happens if a URL tries to peek outside the navigator space, for example navigator/a/b/c/../../../../header?

Parameters

browseDialogTitle:String — The title of the File browse dialog. This is prefixed by a string to indicate to the user that this is coming from the navigator.
 
browseDialogFilters:Array — An Array of FileFilter objects and will be used in the File browse dialog.
 
relativeURL:String — The path where the resource will be added. Must begin with "navigator/". It must be a relative path, "/" separated, but with no leading "/". If the URL does not have a file extension (that is, it does not contain a '.'), then the file extension of the added file (if any) will be appended. If the URL ends with "/", then the entire file name of the selected file will be appended.
 
response:Function (default = null) — An optional notification function, as described above.


Throws
Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

See also

createFolder()method 
public function createFolder(name:String, response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Create a new folder in the current folder.

This operation is only allowed when the permission "EmbeddedFile"/"Create" has been granted.

The method accepts an optional callback function as an argument. The callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void

The response:Object parameter contains properties that define the response. These include:

PropertyTypeValue
successBooleantrue if the operation succeeded; false otherwise.

Parameters

name:String — The folder name. The value null tells the framework to choose a default name.
 
response:Function (default = null) — An optional notification function, as described above.


Throws
Error — Throws an Error if called when the permission "EmbeddedFile"/"Create" has not been granted.

See also

deleteItems()method 
public function deleteItems(attachments:Array, response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Deletes the specified attachments.

If any of the attachments are in the current selection, the host will remove them from the selection (and generate the appropriate notification).

This operation is only allowed when the permission "EmbeddedFile"/"Delete" has been granted

The method accepts an optional callback function as an argument. The callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response:Object parameter contains properties that define the response. These include:

PropertyTypeValue
successBooleantrue if the operation succeeded; false otherwise.

Parameters

attachments:Array — An Array of attachments to delete. Each element is an IAttachment instance. If an element in the array is a folder, then that folder and all its children will be deleted.
 
response:Function (default = null) — An optional notification function, as described above.


Throws
Error — Throws an Error if called when the permission "EmbeddedFile"/"Delete" has not been granted.

See also

Object
Array
IAttachment
deleteResource()method 
public function deleteResource(relativeURL:String, response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Deletes the resource associated with the path.

This operation is only allowed when the permission "Document"/"Modify" has been granted.

Accepts an optional callback function as an argument. When it is non-null, the callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response parameter contains properties that describe the response. These include:

PropertyTypeValue
'success'Booleantrue if the operation succeeded; false otherwise.
'error'StringA non-human-readable String describing the error. It is non-null only if success is false.
'relativeURL'StringThe value of the relativeURL parameter in the function call.

Parameters

relativeURL:String — The path to the resource to be deleted. It must match a path used previously on a successful call to addResource() or writeResource().
 
response:Function (default = null) — An optional notification function, as described above.


Throws
Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

See also

getDirty()method 
public function getDirty(response:Function):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Returns the 'dirty' status of the ICollection. A value of true means that the containing portfolio document has changes that need to be saved.

The portfolio document may be dirty either because of an explicit call to setDirty() or as a result of the user performing some other dirtying operation on it.

The result is returned asynchronously. The single argument is a callback function that receives the result. Its signature is as follows:

function callback(isDirty:Boolean):void

Parameters

response:Function

getLocalizedString()method 
public function getLocalizedString(key:String, defaultValue:String = null):String

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Gets a localized string from the navigator's resources contained in the collection.

Adobe provides support for including sets of localized strings in a navigator's .nav file. See the navigator file format documentation for more details.

Parameters

key:String — A unique key identifying a localized string.
 
defaultValue:String (default = null) — A default value for the localized string.

Returns
String — The string identified by key, localized for the collection's locale. If the collection does not contain such a string, and a non-null defaultValue argument has been specified, defaultValue is returned; if defaultValue was not specified, an empty string is returned.
getSessionData()method 
public function getSessionData(key:String, callback:Function):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Returns session data for the specified key.

The session data is returned via a callback function. The callback function has the following signature:

function (key:String, sessionData:*):void
where sessionData is the requested data (or 'null' if it could not be returned).

The callback function will be called exactly once. This will occur outside the scope of the getSessionData() call.

Parameters

key:String — Key to get the state for.
 
callback:Function — Callback function as described above.

getSessionDataKeys()method 
public function getSessionDataKeys(callback:Function):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Returns keys for all session data associated with this collection.

The session data keys are returned via a callback function. The callback function has the following signature:

function (keys:Array):void
where keys is an Array of String keys.

The callback function will be called exactly once. This will occur outside the scope of the getSessionData() call.

Parameters

callback:Function — Callback function as described above.

registerFonts()method 
public function registerFonts(fonts:Array):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Registers an array of fonts that should be embedded by the host application. Calls to this function are not cumulative; subsequent calls will replace the list of fonts to be embedded, rather than add to it.

Fonts are specified as generic objects with the following properties:

PropertyTypeValue
fontNameStringThe name of the font family to be embedded
fontWeightString"bold" if the bold variant of the font should be embedded; "normal" otherwise.
fontPostureString"italic" if the italic variant of the font should be embedded; "normal" otherwise.
psNameStringIf present, look up the font by "PostScript" name rather than using by name/weight/posture.

Parameters

fonts:Array

See also

reorderFiles()method 
public function reorderFiles(attachments:Array):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Changes the order of a set of IAttachments. The new order will match the order of the IAttachments in the array.

The attachments array should contain all the attachments for one particular folder. Behavior when this is not the case is undefined.

Parameters

attachments:Array — Array of IAttachment instances.

resolvePath()method 
public function resolvePath(relativeURL:String):String

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Given a relative path to a resource, return a URL from which the resource can be loaded. Does not check for existence of the data at the URL.

Sample usage: var url:String = collection.resolvePath("navigator/resourceData.xml"); var request:URLRequest = new URLRequest(url); var loader:URLLoader = new URLLoader(); loader.addEventListener(Event.COMPLETE, dataLoaded); loader.load(request);

If the relative path is not resolved to a URL in this fashion, then the player will assume the path is relative to the application. In some environments (such as when running in Acrobat or Reader), this will work. In others it will not, meaning that reading data in this way will fail.

Parameters

relativeURL:String — Relative path to resolve, with no leading "/".

Returns
String — The URL corresponding to the path.

See also

setDirty()method 
public function setDirty():void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Sets the flag indicating that the ICollection is dirty and needs to be saved. This enables the Save option in the File menu.

setSessionData()method 
public function setSessionData(key:String, sessionData:*):void

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Stores session data under the specified key. If any data already exists for that key it will be deleted.

The session data must be Boolean, Number or String. Alternatively can be null, which causes the key, if it exists, to be deleted along with its data. Deleting a non-existent key is benign.

The following values are illegal and are not accepted:

TypeIllegal Values
NumberNaN, NEGATIVE_INFINITY, POSITIVE_INFINITY
Stringempty String (length == 0),leading or trailing whitespaces

Parameters

key:String — Key under which to save the data. Must be non-null.
 
sessionData:* — The data to store. A null value causes the key and its data to be deleted.

writeResource()method 
public function writeResource(buffer:ByteArray, relativeURL:String, response:Function = null):void

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

Replaces the contents of the navigator custom resource if one exists for the given path or creates a new one otherwise.

This operation is only allowed when the permission "Document"/"Modify" has been granted.

The maximum length of the ByteArray accepted by this method is 1,048,576 bytes.

Accepts an optional callback function as an argument. When it is non-null, the callback function is invoked to indicate the result of the operation. The callback function receives a single argument, an Object, and has the following signature:

    function callback(response:Object):void
The response parameter contains properties that describe the response. These include:

PropertyTypeValue
'success'Booleantrue if the operation succeeded; false otherwise.
'overwrite'Booleantrue if the operation resulted in an existing resource being overwritten; false otherwise.
'error'StringA non-human-readable String describing the error. It is non-null only if success is false.
'relativeURL'StringThe value of the relativeURL parameter in the function call.

Parameters

buffer:ByteArray — The byte array that contains the buffer that will be written to the file.
 
relativeURL:String — The path where the resource will be added/replaced. It must be a relative path, "/" separated, but with no leading "/".
 
response:Function (default = null) — An optional notification function, as described above.


Throws
Error — An Error is thrown if the permission "Document"/"Modify" has not been granted.

See also

Event Detail
needsSave Event
Event Object Type: flash.events.Event

Language Version : ActionScript 3.0
Product Version : Portfolio 9.0
Runtime Versions : Flash Player 10.1, AIR 2.0

This event is dispatched when the navigator should write out any pending data.

sessionDataChanged Event  
Event Object Type: com.adobe.portfolio.api.SessionDataChangedEvent

Language Version : ActionScript 3.0
Product Version : Portfolio 10.0
Runtime Versions : Flash Player 10.1, AIR 2.0

This event is dispatched when session data changes.