CEP 9 HTML Extension Cookbook

This cookbook is a guide to creating CEP 9.0 HTML/JavaScript Extensions for Creative Cloud applications. CSXS is the old name before CS6, and CEP (Common Extensibility Platform) is new name from CS6. When we talk about CEP or CSXS, they refer to the same project.

CEP (formerly CSXS) Extensions extend the functionality of the Adobe point products in which they run. Extensions are loaded into applications through the PlugPlug Library architecture. Starting from CEP 4.0, HTML/CSS and JavaScript (ECMAScript 5) can be used to develop extensions.

These extension types are supported by CEP. You need to specify an extension's type in its manifest.xml.

• Panel
  • The Panel type behaves like any other application panel. It can be docked, participates in workspaces, has fly-out menus, and is re-opened at start-up if open at shutdown.
• ModalDialog
  • A Modal Dialog type opens a new extension window and forces the user to interact only with the extenison window before returning control to the host application. User can interact with host application only after closing extension window.
• Modeless
  • A Modeless Dialog type opens a new extension window but doesn't force the user to interact with the extension window.
• Custom (Since CEP 5.0)
  • This type is for invisible extensions. An invisible extension remains hidden and never becomes visible during its whole life cycle. Read "Invisible HTML Extensions" for more details.

These applications support CEP HTML extensions.

CEP HTML engine is based on Chromium Embedded Framework version 3 (CEF3). You can find more information about CEF here. Here are the versions used in CEP:

CEP supports two kinds of cookies:

• Session Cookies - Temporary in-memory cookie which will expire and disappear when user closes extension
• Persistent Cookies - No expiry date or validity interval, stored in user's file system

Persistent Cookies location:

• CEP 4.x
  • Windows: C:\Users\\AppData\Local\Temp\cep_cookies\
  • macOS: /Users//Library/Logs/CSXS/cep_cookies/
• CEP 5.x
  • Windows: C:\Users\\AppData\Local\Temp\cep_cache\
  • macOS: /Users//Library/Logs/CSXS/cep_cache/
• CEP 6.x and later releases
  • Windows: C:\Users\\AppData\Local\Temp\cep_cache\
  • macOS: /Users//Library/Caches/CSXS/cep_cache/

Each persistent cookie is a file. File name is HostID_HostVersion_ExtensionName, such as PHXS_15.0.0_com.adobe.extension1.

There is no migration required for the extensions working in CEP 8. Extensions running on CEP 8 should run on CEP 9 out of the box. 

Note: element in manifest file is mandatory as per the documentation but it used to work by taking max or min size provided in the manifest till CEP 8, this bug has been fixed in CEP 9. Please ensure to define element in your manifest.

Please follow [Guide for migrating from CEP 7 to CEP 8](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_9.x/Documentation/CEP%209.0%20HTML%20Extension%20Cookbook.md#guide-for-migrating-from-cep-7-to-cep-8)

Please be aware that, we are moving to chromium version 57.0.2987.74 from 41.0.2272.104. Similarly for nodejs, we are moving to 7.7.4 from iojs 1.2.0. This migration guide is written based on CEP team's testing and if you find any new issues, please document or share with CEP team.

Following Chromium APIs have been removed:

• MediaStream.label, MediaStream.ended and MediaStream.stop()
• Remove getUserMedia() from Insecure Contexts
• SVG hasExtension() methods
• SVGSVGElement.pixelUnitToMillimeterX and friends
• Fetch API: Deprecate and remove Request.context
• Document.charset setter
• NPAPI plug-in support Range.compareNode() and Range.expand()
• WebAudio: Disallow setting AudioBufferSourceNode.buffer more than once
• Deprecate and remove SVGViewElement.viewTarget attribute
• Deprecate SVGSVGElement.viewport attribute
• Remove FileError interface
• Deprecate and remove: WebKit legacy window.postMessage() overload
• Deprecate and remove: 'results' attribute for

Below listed changes are applicable when --enable-nodejs is passed as CEFCommandline parameter.

CEP 8 and later versions introduces additional symbol: cep_node in the global context when nodejs is enabled. cep_node will hold following node specific symbols:

cep_node members Buffer, global, process and require

nodejs symbols will not be available in iframe's global context, only way you can access nodejs APIs within iframe's context is through cep_node. When --mixed-context is enabled, global node symbols and cep_node is available within iframe's global context as browser and node gets executed at the same context. It is also important to note that, if you have existing code to check or use nodejs symbols in iframe's global context, it used to work till last release and in the current release, it breaks in separate context mode.

Newly integrated nodejs adds "module" and "exports" symbols to the global context. Many libraries such as JQuery relies on its booting based on the availability of "module" symbol in the global scope. For ex, JQuery has following code while booting:

JQuery startup code

if ( typeof module === "object" && typeof module.exports === "object" ) {
    // set jQuery in `module`
} else {
   // set jQuery in `window`
}

When this code is executed in CEP's browser with nodejs enabled, it will make JQuery to load in module context instead of Browser context. This would cause issues to extension's startup. Please use below code to handle such scenarios:

global symbols handling

if (typeof module === 'object') {window.module = module; module = undefined;}
if (typeof exports === 'object') {window.exports = exports; exports = undefined;}




if (window.module) module = window.module;
if (window.exports) exports = window.exports;

If you are not using "module" and "exports" in the extension, you could skip last 2 lines of above code. This logic is similar to how users handled nodejs's require while importing. If you are handling require already, you should continue to handle same way.

Nodejs 7.7.4 or higher versions requires path to be included as absolute path. So, if you have nodejs require for the js file,replace the path to absolute instead of relative. For eg. replace:

require("./js/lib/jquery.js");

with

Win require absolute path for nodejs

var loc = window.location.pathname;
var dir = decodeURI(loc.substring(1, loc.lastIndexOf('/')));
require(dir + "/js/lib/jquery.js");

On macOS (there is a change in index passed on to substring)

macOS require absolute path for nodejs

var loc = window.location.pathname;
var dir = decodeURI(loc.substring(0, loc.lastIndexOf('/')));
require(dir + "/js/lib/jquery.js");