Adobe VERSION CUE CS3 User Manual

ADOBE VERSION CUE CS3 CLIENT PROGRAMMER’S GUIDE

Adobe Version Cue CS3 Client Programmer’s Guide

Technical note #10306 Adobe, the Adobe logo, Bridge, Creative Suite, Version Cue, and Version Cue Server are either registered trademarks or trademarks of Adobe

Systems Incorporated in the United States and/or other countries. Mac OS is a trademark of Apple Computer, Inc., registered in the United States and other countries. Windows is either a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.

The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license.

Contents

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Key Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Customizing Asset Icons/ Thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Custom Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Modifying Project Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Downloading and Syndication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Customizing the Check-in Dialog: Metadata Capture and Enforcement. . . . . . . . . . . . . . . 14

Customizing Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Customizing the Search Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Version Cue Client Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Version Cue Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Client Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Server-driven Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Multi-threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Scripting Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

ExtendScript: a JavaScript implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Debugging, Logging, and Profiling with the Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Preprocessor Directives in ExtendScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Application and Version Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Writing Client-side Scripts for the First Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Contents

4 Adobe Version Cue CS3 Client Programmer’s Guide

Adobe Version Cue CS3 Client Programmer’s Guide

This document describes the Adobe® Version Cue® client from a programmer’s perspective. It is intended for system integrators integrating with Version Cue, who are already writing plugins for Version Cue Server™.

This document describes the extensibility features enabled by Version Cue SDK at the Version Cue clients such as Adobe Bridge® CS3, and how you can extend Version Cue clients to connect Adobe Creative Suite® 3 to an external system; for instance, a digital asset management (DAM) system.

The extensibility model for Version Cue client is based on server-driven scripting. JavaScript code can be sent from a Version Cue Server plug-in to a Version Cue client, to modify the client’s user interface and/or provide additional logic.

We describe the scripting interface at a conceptual level and indicate how to start writing the JavaScript needed to integrate with and extend the Version Cue client. In addition to sending scripts from the client to the Version Cue Server, you can also extend the SOAP protocol that is used to communicate between the clients and Version Cue Server to enable your own custom operations to be triggered at the server-side and we discuss how this protocol extension fits into the extensibility model.

Ter mi no lo gy

It may also be necessary in some cases to add a client-side component that uses the Version Cue client scripting interface but that you cannot deliver through a server-driven JavaScript. For instance, if you want to add a new tabbed palette to the user interface of Adobe Bridge CS3 that was integrated with your external system through the Version Cue Server, then you would have to install the JavaScript code to create this tabbed palette as a separate client-side component. We provide some basic guidance on what you can achieve with the model of serverdriven JavaScript, and when you might have to add some client-side components that cannot be delivered by server-driven scripts.

Terminology

z Adobe Bridge™ — Adobe Bridge CS3, a particularly privileged Version Cue client. z ExtendScript — An Adobe implementation ECMA-262 JavaScript specification, used by

Creative Suite applications.

z ExtendScript Toolkit (ESTK) — An integrated development environment (IDE) developed

by Adobe for writing and debugging JavaScript code. To develop JavaScript code for Creative Suite CS3, you must use the latest version of ExtendScript Toolkit 2.0.

z Version Cue client — The client component of Version Cue CS3. This is a point product in

Creative Suite CS3. This is a client of the Version Cue Server and uses the Version Cue pro- tocol to communicate with the Version Cue Server.

Adobe Version Cue CS3 Client Programmer’s Guide 5

Adobe Version Cue CS3 Client Programmer’s Guide

Introduction

z Version Cue Ser ver — The server component of Version Cue CS3. z Version Cue Server plug-in — A plug-in developed in Java™ using the Version Cue SDK,

conforming to the pattern required to be loaded and called by Version Cue Server.

NOTE: Unless noted otherwise, references to any Adobe product always mean the CS3

product.

Introduction

Version Cue clients, such as Adobe Bridge CS3 or Adobe InDesign® CS3, are integrated with the Version Cue CS3 client libraries (Windows DLLs or Mac OS frameworks) and can be programmed through the scripting interface to these libraries, which is a JavaScript API. This scripting interface allows you to customize the user interface of the Version Cue client and have your own JavaScript code execute at the client. For details, see the Scripting Interface Ref- erence, which is included in the Help system of the IDE for Version Cue SDK.

Point products in the Adobe Creative Suite CS3, like Adobe InDesign CS3 and Adobe Photoshop CS3, use the Adobe Common User Interface, such as the Adobe File > Open dialog. The dialog enables end users to open a file with a uniform user experience on both Mac OS® and Windows®. The Adobe Common User Interface is an alternative to platform-specific file-open dialogs, with divergent behaviour on Mac OS and Windows.

Another key aspect of the Adobe Common User Interface is that it integrates with Version Cue and enables end users to interact with Version Cue Server; for example, check out files for editing, see historical versions of a file, check in a version to Version Cue Server, and search for assets matching a specification on a Version Cue Server.

We recommend using Adobe Bridge CS3 to exercise Version Cue extensibility features illustrated by the Version Cue SDK sample plug-ins, as it has the deepest integration with Version Cue. However, you should also try using the Adobe File > Open dialog and other elements of the Adobe Common User Interface from point products in Creative Suite CS3, such as Adobe InDesign CS3 or Adobe Photoshop CS3, to understand how the extensibility enabled by Version Cue shows up in the other components of the Adobe user interface.

Key Operations

Customizing Asset Icons/ Thumbnails

A key aspect of Version Cue extensibility is customizing how assets appear in the Adobe Common User Interface; for example, providing your own choice of icons or thumbnails for projects, folders, or files. The same extensibility mechanisms that operate in the Adobe Com-

Adobe Version Cue CS3 Client Programmer’s Guide

Key Operations

mon User Interface also let you customize how assets appear in the user interface of Adobe Bridge CS3, which is tightly integrated with Version Cue.

To see the the Adobe File > Open dialog from the Adobe Common User Interface, using a client such as Adobe InDesign CS3. If the normal operating-system file-open dialog appears instead of the Adobe dialog when you are trying this for the first time or after deleting preferences, click the button labelled “Use Adobe Dialog” in the bottom left-hand corner of the operating-system dialog. To browse Version Cue projects, select the Version Cue item in the lefthand panel of this dialog and navigate to the Version Cue Server that you just launched, the name of which should appear in bold.

If you are using Adobe Bridge CS3, then you can browse Version Cue Servers directly from the Favorites panel, which should show a root node named Version Cue. If you click on this node, then you will see the Version Cue Server instances that are visible from your client; these are displayed within the Bridge Content pane. If you navigate into a specific Version Cue Server by clicking on its icon, then the Version Cue projects on that Server can be seen in the Content pane of Bridge, as in Figure 1.

FIGURE 1 Custom Thumbnails for Version Cue Projects in Adobe Bridge CS3

Figure 1 shows a customized project appearance in the user interface of Bridge for “Sample

Custom Project”; note how the thumbnail differs in color and form from the other projects shown.

Note that this custom appearance can be viewed in both Bridge and the Adobe Common User Interface, in the context of the Adobe File > Open, File > Place and File > Save dialogs. Ideally, your custom projects— connected to your own digital asset management system, say— will have a different appearance than the standard Version Cue projects, as in this example.

Adobe Version Cue CS3 Client Programmer’s Guide 7

Adobe Version Cue CS3 Client Programmer’s Guide

Key Operations

The custom project icon in Figure 1 is provided by a sample plug-in for Version Cue Server named sample.customproject; this sample plug-in is the reference implementation for connecting to an external system and provides a model of how you would implement an adapter between your external system and the Adobe Creative Suite CS3 point products.

Selecting projects in the Content pane of Bridge or the Adobe File > Open dialog and doubleclicking to explore them— or using the context-sensitive menu item Open— has the side effect of mounting the projects, at which point resources may be sent by the Server to modify the user interface to the project or contribute additional logic.

In addition to customizing the icons for projects, you can customize how folders display in the Adobe user interface. Figure 2 shows an example of a standard Version Cue project displayed in Adobe Bridge CS3, with a drop folder provided by the SDK sample named sample.dropfolder. The folder named sample.dropfolder displays a different icon than a standard folder.

FIGURE 2 Customized Icons for a Folder

You also can customize the thumbnails/icons displayed at the level of individual files. See the SDK sample named sample.customproject for an example of providing custom thumbnails for file-based assets; see the Thumbnail implementation class in that sample.

Note that there are extensibility mechanisms to enable you to customize the appearance of assets in the Adobe user interface for both assets in your own external projects and standard Version Cue projects. Note also that asset in the context of Version Cue is a generic term, which can be used to refer to a project, a folder or a file.

For More Information

See the following resources:

z VersionCueSDK IDE Help > Version Cue SDK Help > Samples Guide > CustomProject z VersionCueSDK IDE Help > Version Cue SDK Help > Samples Guide > DropFolder

Custom Metadata

Version Cue clients can display custom metadata provided by your Version Cue Server plugins, in contexts such as the Inspector Panel of Adobe Bridge CS3 or the File Info area of the Adobe File > Open dialog.

The Inspector Panel in Adobe Bridge CS3 is a read-only metadata view component of the Bridge user interface, which lets per-asset metadata be visualized; it is entirely different from the standard Bridge Metadata panel, which is used to display and edit XMP-based metadata.

Figure 3 shows a view of custom metadata for an asset selected in the Content pane of Adobe

Bridge CS3. The Inspector Panel displays custom metadata for a file selected in the Content pane.

FIGURE 3 Inspector Panel in Bridge showing Custom Metadata

Adobe Version Cue CS3 Client Programmer’s Guide

Key Operations

Note that for a Version Cue Server plug-in to display metadata in a context such as the Inspector Panel, one of its responsibilities is to advertise a particular project capability to the Version Cue clients; in this case, the capability to overwrite the metadata view at the Version Cue client for assets within a particular project. In “Modifying Project Capabilities” on page 9, we exam- ine what capabilities are in a little more detail.

For More Information

See VersionCueSDK IDE Help > Version Cue SDK Help > Samples Guide > Custom Metadata

Modifying Project Capabilities

In addition to advertising the additional capabilities a Version Cue Server plug-in supports for a given project, the Version Cue Server plug-in also can restrict or remove capabilities from the default set, or provide only a specific subset. For instance, this extensibility feature can be

Adobe Version Cue CS3 Client Programmer’s Guide 9

Adobe Version Cue CS3 Client Programmer’s Guide

Key Operations

used to remove menu items from the context-sensitive menu shown when an asset is selected in one of your custom projects, if some operations are not supported.

Figure 4 shows context-sensitive menu items when a file in a standard Version Cue project is

selected in Adobe Bridge CS3. Note how there are nearly twenty menu items shown for this context-sensitive menu.

FIGURE 4 Context-sensitive Menu for Standard Version Cue Project

Figure 5 shows the context-sensitive menu when an asset is selected in “Sample Custom

Project”; note there are only around ten context-sensitive menu items shown— around half the number compared to a standard project as shown in Figure 4. The custom project has reduced functionality compared to the standard project, and so the Version Cue Server plug-in that provides the custom project needs some way to communicate to the Version Cue client that the set of functionality has been restricted.

Adobe Version Cue CS3 Client Programmer’s Guide

FIGURE 5 Context-sensitive Menu for Custom Project

Key Operations

This is achieved by restricting the project capabilities that sample.customproject provides. See the ProjectCapabilities class in that sample to discover why there are fewer menu items for the context-sensitive menu on the custom project compared to the standard project.

For More Information

See VersionCueSDK IDE Help > Version Cue SDK Help > Samples Guide > CustomProject To find out what capabilities exist in the API, look in the API Reference under ICapability; you

will see asset, metadata, project and search capabilities. These are of interest if you want to add to or subtract from the default set of capabilities of a standard Version Cue project and you need to know how to declare these.

Downloading and Syndication

Download and syndication of assets between an external project and a standard Version Cue project is supported by drag and drop in the user interface of Adobe Bridge CS3 only. In this process, assets are transferred from an external project, typically with read-only access, to a standard project. Syndication is the process of transferring the asset. The destination (standard) project is referred to as the work-in-progress (WIP) project.

After syndication, the user can work on the asset in the standard project exactly as on any other standard Version Cue asset and take advantage of all the Version Cue features that are available, such as versioning assets. The Version Cue Server stores a back-link or external ref- erence to the original external asset, by saving some asset-level metadata along with the asset in the standard Version Cue project.

Adobe Version Cue CS3 Client Programmer’s Guide 11

+ 23 hidden pages