Skip to content

Client-side debugging

This guide will walk you through the necessary steps to debug client-side code in a CEP extension.

Contents

Prerequisites

This guide will assume that you have completed all steps in the Getting Started with CEP Extensions Guide.

Set the Debug Mode

First, set the following Adobe preference to prevent your host application (Photoshop, InDesign, etc.) from throwing alerts about unsigned extensions. The HTML Extension Cookbook section on Debugging Unsigned Extensions explains this process:

Windows: Open regedit > HKEY_CURRENT_USER/Software/Adobe/CSXS.8, then add a new entry PlayerDebugMode of type "string" with the value of "1".

Mac: In the Terminal, type: defaults write com.adobe.CSXS.8 PlayerDebugMode 1

This is what Regedit looks like in Windows 10. You can access it using CMD, too. On Windows, Regedit is located in (C:\Windows\regedit). You can access it using CMD, too.

Here's what Terminal looks like in MacOS Sierra.On macOS, Terminal is located in (Applications > Utilities > Terminal).

Create a .debug File

Next, create a .debug file for your extension. The .debug file needs to be at the top level of your extension's folder.

Your panel's directory

The .debug file must be a hidden file in order to work. The . at the front of the file name will make it hidden. The easiest way to create this file is to use the code editing tool of your choice (like Sublime Text or Brackets) to create a new file named .debug.

To see your hidden files on Mac, as of MacOS Sierra, you can use the Command Shift + shortcut.

To see your hidden files on Windows 10, you can expand your view options in a File Explorer window and check the Hidden Files box.

How to see your hidden files in Windows 10.How to see your hidden files in Windows 10.

Write Contents for the .debug File

The .debug file must include the following elements (see notes #1-2 below):

    <ExtensionList>
        <!-- 1 -->
        <Extension Id="com.example.helloworld">
           <HostList>

               <!-- 2 -->
               <Host Name="PHXS" Port="8088"/>
               <Host Name="PHSP" Port="8088"/>

            </HostList>
        </Extension>
    </ExtensionList>

  1. The Extension ID in this .debug file above must match the Extenstion ID in your manifest.xml file (see our Getting Started Guide for more information).

  2. List the Host IDs for each app your extension supports, with a corresponding port of your choosing for debugging. In this example, we've listed the Host IDs for Photoshop. The full list of host application ports is available in the CEP Cookbook.

Debugging in Chrome

Open Chrome and go to http://localhost:8088/ or whichever port you set in your .debug file in the previous section.

CEF Remote Debugging in Chrome CEF Remote Debugging in Chrome

If your panel is working, you'll see the name of your extension as a link you can click on, as seen in the image above. The link will take you to the JavaScript Console within Chromium DevTools. The JavaScript Console is where, among other things, you will see your extension's log and error output.

The JavaScript Console in ChromeThe JavaScript Console in Chrome

In the example below, the console.log() message is "I can't believe you clicked!":

<html>
<head>
    <title>Hello World!</title>
</head>
<body>

    <h1>Hello World!</h1>

    <!-- Add a button labeled "Click this!" -->
    <button id="myButton">Click this!</button>

    <script type="text/javascript">
    /* Add a click handler to the button */
    document.getElementById('myButton')
        .addEventListener('click', function() {
            /* When the button is clicked, output a string to the JavaScript Console */
            console.log("I can't believe you clicked!");
        });
    </script>

</body>
</html>

Troubleshooting common issues

Getting a "not properly signed" alert

The change in the Set the Debug Mode section is invisible if performed correctly. Otherwise, you'll get the following error about unsigned extensions:

*The "Your Panel Name" extension could not be loaded because it was not properly signed.*The "Your Panel Name" extension could not be loaded because it was not properly signed.

Don't worry about signing your extensions until you're ready to distribute to users.

If you've set the debug mode and are still getting the error above, try killing the cfprefsd process, or check out this thread about troubleshooting debug mode in the Adobe forums.

Getting a blank debug console

If your debug console in Chrome appears blank, check the contents of your .debug file one more time:

  • Does your extension ID in the .debug file match what's in manifest.xml?
  • Are you listing the supported host app(s) correctly with the right Host ID(s)?
  • Are you attempting to access localhost on the same port that you have indicated in your debug console?

If you are still having trouble, try following the steps on this Adobe forum thread.

Next Steps

Now that you've seen the basics, check out these guides and samples that walk you through some common intermediate and advanced topics in building CEP extensions:

Other Resources

Attribution

This debugging guide incorporates information from multiple sources and has been enhanced with community-contributed knowledge about CEP extension debugging practices.

Special thanks to all the developers who have contributed their debugging knowledge and experience to help make CEP extension development more accessible.