Table of contents

Created

Requirements

Prerequisite knowledge

User level

All

This article will walk you through the entire process of creating an Adobe CC HTML extension from scratch. The resulting extension will allow you to augment the functionality of an Adobe application using HTML, JavaScript, ExtendScript, and CSS.

At the root of the manifest, we provide the id, human readable name, and version of the extension bundle. A bundle is just a collection of extensions; in this bundle, we'll only have one extension to keep things simple. The attribute Version="4.0" should be hardcoded; it defines the manifest version, everything else is up to you to define.

Here we specify the list of extensions along with their ids and versions. Again, for this example, we only have one extension.

<HostList>

<HostList>
<Host Name="PHXS" Version="[14.0,14.9]"/>
</HostList>

In the <HostList> section, we define a list of applications our extension will work with. Each application is identified by a 4 character code along with a version range. In this case we're targeting Photoshop CC.

<LocaleList>

<LocaleList>
<Locale Code="All"/>
</LocaleList>

The <LocaleList> section defines the locales your extension will work in. Here we've set up the extension to work for all locales.

Finally, we have the <UI> section. Here we define the window type of the extension, the menu name (which will show up under Window > Extensions), and the initial dimensions.

Running the extension

Now that we have our code ready to go, the next step is to prepare our environment for development and copy the extension into place. Then we can run the extension.

PlayerDebugMode

Applications will normally not load an extension unless it is cryptographically signed. However, during development we want to be able to quickly test an extension without having to sign it. To turn on debug mode:

On Mac, open the file ~/Library/Preferences/com.adobe.CSXS.4.plist and add a row with key PlayerDebugMode, of type String, and value 1.

On Windows, open the registry key HKEY_CURRENT_USER/Software/Adobe/CSXS.4 and add a key named PlayerDebugMode, of type String, and value 1.

You should only need to do this once.

Copying the extension into place

Now that the system is ready to load our unsigned extension, the last thing we have to do is copy our extension into the shared extensions folder on disk:

On Mac, copy the extension into ~/Library/Application Support/Adobe/CEPServiceManager4/extensions

On Windows, copy the extension into %APPDATA%\Adobe\CEPServiceManager4\extensions

When you're done you should have a folder structure like this:

extensions/
HelloWorld/
CSXS/
manifest.xml
index.html

Opening the extension

Now we can open the extension in Photoshop CC. Launch the application and choose the menuWindow > Extensions > Hello World. You should see something like this:

Debugging

Our extension is up and running, now let's debug it.

There are two ways to debug an HTML5 extension.

Method 1 (Deprecated): Debugging can be enabled by calling a special JavaScript function that only works for extensions:

window.__adobe_cep__.showDevTools();

Add this line to a file named main.js and reference the new file from index.html:

Note: The above step is necessary with more recent versions of Creative Cloud products. At the time of writing it is only required with Premiere Pro 7.1 and Illustrator 17.0.2. For other products it is not required.

To use this method, you must specify debug ports in a mapping file in your extension's root folder. You can then open the debug port for the host application from a Google Chrome browser and use the Chrome debugging tools. For example, if you have specified the debug port 8088 for Photoshop, and you open your extension in Photoshop, open the Chrome browser and go to http://localhost:8088. Mozilla Firefox and Safari should also work. The browser will display information about your extension and a clickable link to debug the extension. Once you click on that you will see a similar view as when using Method 1.

To specify the debug ports, create a special file named .debug and place it in your extension's root folder; for example, MyExtension\.debug.

Edit this file to include valid remote debug ports for all applications you wish to debug, in the Extension Manifest XML format for <Host> specifications. Valid port values are in the range 1024 to 65534.

Interacting with the host application

In most cases, your extension won't just be isolated HTML, you'll probably want to interact with the application your extension is running in. To make such calls, we use a library called CSInterface.js (this API is documented in Extension Builder 3).

This library provides a number of useful functions, everything from retrieving the id of the current host application, to programmatically closing your extension. For this demo, we're going to use it to make calls against the host application's scripting DOM.

First, we need to add the library to index.html and copy it into the js folder:

Finally, when we reload the extension and click on the button, Photoshop should create a new document.

Note: You may also want to check out CEPEngine_extensions which provides APIs to manipulate local files and external processes.

Packaging for deployment

Once our extension has been developed, we'll eventually want to sign and package it for deployment. For that, we're going to use a tool called ZXPSignCmd which is available at the bottom of the Extension Builder 3 download page.

Certificates

Before we can sign and package our extension, we need a certificate. In the real world, we'd buy a certificate from a trusted certificate authority like VeriSign, but for simplicity let's create a self-signed certificate. We can use ZXPSignCmd to self-sign a certificate using the syntax: