Developing extensions for multiple versions of the Creative Suite

Additional required Adobe products

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

In CS5, developers of Creative Suite extensions didn't have to worry about versioning, because a Creative Suite extension only worked in CS5. In CS5.5, developers now have to consider versioning when creating extensions. And before you think this doesn't apply to you, rest assured that your end users have every CS version under the sun. With a little foresight, you can create extensions that work in both CS5 and CS5.5.

One of key goals during the development of Extension Builder 1.5 was to make creating a multiversion extension as painless as possible for a developer. This article covers the basics of adding multiversion support to your extensions using Extension Builder. We'll also discuss changes to the tooling and what you need to consider when making an extension compatible with multiple versions of Creative Suite.

Basic support for both CS5 and CS5.5 is automatic in Extension Builder 1.5. When you use the New Project wizard, your project is created with the minimum version set to CS5 and no defined maximum version. This means that your extension can theoretically be installed in all versions greater than or equal to the minimum defined version. This is a change in Extension Builder 1.5; extensions created with Extension Builder 1.0 are automatically configured to work in CS5 and later.

Of course, we know that an extension can't continue to work forever; technologies and APIs change over time. However, for the short term it's true; with the minimum version set to CS5 and no defined maximum version, you can install your extension into CS5.5.

If you want to be more explicit about the versions your extension works with, you can specify the maximum supported version for your extension. The range is inclusive. For an existing project, you can change the minimum and maximum supported version using the Bundle Manifest Editor. This tool saves you from the complexity of manually editing the manifest.xml configuration file required for each extension, but if you're interested, you can see how an extension keeps track of its versioning information:

1. To open the Bundle Manifest Editor, right-click your project and choose CS Extension Builder > Bundle Manifest Editor.
2. Set a minimum and maximum target version on the General Information tab:

3. To see the effect, open the manifest.xml tab.
4. Locate the element that looks like this:

This entry means that your extension is targeting InDesign version 7.0 (CS5) and later. If you define a maximum version, it looks like this:

An extension with this configuration can only be installed in InDesign CS5 and CS5.5, and no other versions.

If you do decide to target multiple versions for your extension, you might also need to decide which version of the CSAW libraries to use. For most use cases, it won't matter, but it might if you want to use features that were added to the scripting DOM of your target product in a new version. By default, Extension Builder chooses the CSAW library built for the minimum version in your project range, but you can choose any CSAW library version within your project version range. Because APIs typically grow over time, the default configuration is the safest; you’ll probably be using APIs that are available in all versions. If, however, you want to use new features that have been added to the scripting DOM, you must use the latest CSAW version to get access to the API for those features. If you do this, you must be careful to make the calls only when your extension is running in a context that can handle them.

To check the availability of any scripting DOM feature in a particular product release, refer to the API references included with Extension Builder. To change the version of the CSAW library your extension compiles with, use the newly revamped CS Extension Builder Libraries section in Extension Builder 1.5:

1. Right-click your project and choose Properties.
2. In the left navigation panel of the Properties dialog, select CS Extension Builder Libraries.
3. Select "Show all CS Versions."
4. On the Creative Suite tab, select the version of the CSAW library you need for each target product.
5. Click OK.

When you use Extension Builder 1.5 to launch an extension that targets multiple versions, it behaves differently depending on your environment.

• If you only have one version of the target product installed, Extension Builder automatically chooses that version and launches it; this is the same as before.
• If multiple versions are installed in your project range, Extension Builder prompts you to choose which version to launch.

You can tell Extension Builder to remember your version choice and automatically launch that version in the future. To change this option, edit the corresponding launch configuration:

1. Right click your project, and choose Debug As > Debug Configurations.
2. In the navigation panel on the left, expand the product for which you want to change the launch configuration.
3. Select the launch configuration named for your project.
4. In the Target Version menu on the right, choose "undefined".
5. Click Apply.

In general, you don't have to do anything special to make export and deployment work properly. During export, Extension Builder automatically packages your manifest (which contains the version information), and Extension Manager reads this to determine whether the extension can be installed in a given version of an application.

You do have to make sure that the version of Extension Manager matches the version of the target application. For example, if your end user has both CS5 and CS5.5 installed, and your extension is configured to work only with CS5, the user must use Extension Manager CS5 to install the extension. You have to make sure your users know this, because CS5.5 is the default; that is, when you double-click a ZXP package, Extension Manager CS5.5 opens automatically and attempts to install the package. If you choose to restrict the versions your extension works with, you are responsible for making sure your users install it with the correct version of Extension Manager.

After reading this article you should have a high-level understanding of how to handle versioning issues in Creative Suite extensions using Extension Builder. Now it's time to do the fun part, code!

For more information, refer to the documentation that is bundled with Extension Builder. The Getting Started and Programmer's Guide sections provide detailed explanations of these new features, and the API references section provides information on which APIs are available in various versions of the applications.

If you have any questions or feedback, we'd love to hear from you:

• Extension Builder Forum
• CS SDK Forum