Developing hybrid extensions with Creative Suite Extension Builder

Additional required Adobe products

• At least one Creative Suite 5 (or later) product

A Creative Suite hybrid extension is the solution for developers who want to build extensions with rich Flash-based interfaces and still take advantage of application-specific extensibility. This solution is ideal when:

• You have legacy code that you want to support.
• The feature you are developing requires a capability supported by the native scripting or C/C++ API layer that is not accessible through your Creative Suite extension; for example, some applications allow you to create custom menus using C++ extensibility.
• You have CPU-intensive tasks to perform that are more suited to C++ than to ActionScript.

Extension Builder packages the components of a hybrid extension into a single ZXP package. Extension Manager installs the package on the user's machine as a single extension.

If you have experience writing Creative Suite extensions and native application extensions (for example, a Photoshop or InDesign C++ extension, a Flash Pro C extension, or a Dreamweaver JavaScript extension), there's little more you need to learn. The two parts of a hybrid extension are implemented as standalone components.

This article shows you how to use Extension Builder 1.5 to package the multiple components as a single Creative Suite extension, including these steps:

1. Adding additional resources to an existing Extension builder project
2. Exporting your Creative Suite hybrid extension
3. Installing the hybrid extension through Extension Manager

Before getting started, perform the following tasks:

• Create a Creative Suite extension using Adobe Creative Suite Extension Builder.
• Create a C/C++ or scripting API plug-in using the application-specific SDK and recommended tools. If you haven't built a native plug-in for your host application, refer to the application-specific SDKs for details. You can download application-specific SDKs from Adobe Developer Connections.

After you've created your application-specific plug-in or extension, you must add the final build to your Adobe Creative Suite Extension Builder project.

Organizing your resources

Create a folder in your Extension Builder project root, name it something like cs_resources, and copy in all of the files that need to be included in the final hybrid extension. If you're adding native plug-ins, add the files for the release version of each plug-in for each supported platform. You can organize the resources by platform. This image shows an example folder structure for a native Photoshop plug-in that supports Mac OS, Win32, and Win64:

Configuring the hybrid extension

After copying the additional resources to the project, you must add those files to the extension using the Bundle Manifest Editor.

1. Right-click in the Creative Suite extension project and choose CS Extension Builder > Bundle Manifest Editor.

2. In the Bundle Manifest Editor, select the Hybrid tab.
3. Under General Information, select the "Hybrid Extension" option. This tells Extension Builder that the project is a hybrid extension project.
4. In the Name box, type a name for the hybrid extension, or keep the default name. This is the name the user sees when the extension is installed using Extension Manager. The default name is the extension bundle ID, but you can change it to a more user-friendly display name.
5. Click Add to add the resources to the manifest.
6. In the File details dialog, fill in information about each resource you want to package with your extension.

Specify the following information for each resource:

Source: The relative location of the resource in the project. Click Browse to choose from among all the resources in the project.

Destination: The location in the file system where you want Extension Manager to install the resource. This is a path token defined in the product-specific SDK or a global path token known to the Extension Manager; see Extension Manager Configuration Reference. Click Select for a list of options, or update the field directly with the appropriate token.

Products: The target product or products for the resource. Separate multiple products with commas. If no product is specified (which is the default), the Extension Manager attempts to install the resource in all products that the extension supports. For example, you can use this to specify a Photoshop resource that should only be installed in the Win64 version (Photoshop64). This attribute is supported only for CS5.5; for CS5, it's ignored.

Platform: The platform the file is intended for. If you specify a platform, the file is installed only on that platform; for instance, you can provide two versions of a file, one for Windows and one for Mac OS, and specify a platform value for each.

File Type: The value "plugin" flags the file as part of a plug-in for InDesign/InCopy CS5 or higher. Use the default value "ordinary" for any other files.

7. Click OK to add the resource.
8. Click Add to add additional resources.
9. After adding all resources, save the bundle to commit the changes. The first time you save the bundle that marks an extension as a hybrid, Extension Builder generates and adds an MXI configuration file to the root of your project. Every time you make changes to the bundle editor, it updates that MXI file.

The MXI configuration file

The generated MXI file is an XML configuration file that Extension Manager uses to correctly install the extension and its components in the user's environment. The generated MXI file looks like this:

This file includes the display strings that Extension Manager uses when the extension has been installed, including the author, description, and legal text. These values are copied from those in the CS Extension manifest, if those are already set.

The Creative Suite extension component has already been added as a file element of type CSXS. Make sure you don't delete or edit this file element. If it's not present, the Extension Manager can't install your Flex-based component. In this case there’s no need to indicate the destination; Extension Manager knows about the shared installation location used by Creative Suite extensions. The Creative Suite extension component isn't listed in the hybrid page of the Bundle Manifest Editor.

We recommend using the Bundle Manifest Editor to make any modifications to the MXI file. However, if you need to add further details to the MXI that aren’t accessible through the editor, you can update the XML file manually. New elements or attributes that you add directly to the MXI XML manually aren't overwritten by the Bundle Manifest Editor when you update the information there. However, if you manually update elements of the MXI that are controlled by the editor, those values are overwritten the next time you update using the editor. These values include:

• Author name
• Extension description
• Legal text
• Product names and versions
• Extension version

Testing a hybrid extension

During development, test the components of your hybrid extension separately.

• Use Extension Builder to launch the Creative Suite component using the Run As, Debug As, or Attach As option.
• Install the application-specific plug-in or extension in the host as instructed in the application-specific SDK. Debug it using the recommended development tools, such as XCode or Visual Studio.
• Install the plug-in component by copying the files to the Plug-ins or Extensions folder, or pointing the host application to your plug-in build folder. For example, InDesign looks for plug-ins in the <InDesign installation location>/Plug-ins/ folder.

  Note that Extension Builder doesn't copy the additonal resources to the destination location during development.

The Extension Builder Export wizard automates the process of packaging a hybrid extension. To create a signed ZXP package that Extension Manager can use to install your hybrid extension:

1. Right-click your project and choose Export.
2. Select Adobe Creative Suite Extension Builder > Creative Suite Extension.
3. Browse to your certificate and enter a password.
4. Select the "Create a hybrid extension that bundles Creative Suite resources" option.
5. Click Finish.

If you want to explore the contents of the packaged extension, select the "Unpack ZXP into export folder" option. The expanded archive is unpacked in the export directory.

Double-click the generated ZXP file in the file browser to install it using Extension Manager.

After Extension Manager verifies the contents and signature and successfully installs the extension, it appears in the list of available extensions for the supported applications. When you select your hybrid extension, you can see the author, description, and legal information specified in the MXI file, as well as the certificate information.

Here are some useful resources to use when developing your Creative Suite hybrid extension:

• Creative Suite Extension Builder documentation
• Creative Suite Native application SDK for information on how to communicate between your Creative Suite extension ActionScript layer and your C++ plug-ins (Requires access to the Adobe Enterprise Developer Program (AEDP))
• Flex Developer Center
• Photoshop native SDK
• InDesign native SDK
• Illustrator native SDK
• Dreamweaver extensibility
• Extension Builder Forum
• CS SDK Forum