Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adobe-cep/getting-started-guides

Getting Started guides and samples for CEP extensions
https://github.com/adobe-cep/getting-started-guides

cep cep-extension extendscript html illustrator indesign javascript photoshop

Last synced: 9 days ago
JSON representation

Getting Started guides and samples for CEP extensions

Awesome Lists containing this project

README 

        
# Getting Started with CEP Extensions



CEP (Common Extensibility Platform) lets you build extensions in Adobe Creative Cloud applications like Photoshop, Illustrator, InDesign, After Effects, and many more. Extensions built with CEP let users customize their Creative Cloud experience for their unique workflows.



In this guide, we will help you quickly get started building a CEP extension by covering the basics in 6 easy steps.



By the end of this guide, we will have a CEP extension that opens a new document from the user's local folder.



![Example extension: opening a new file in Photoshop](.meta/readme-assets/extension.gif?raw=true)



When you're finished, be sure to check out the [Next Steps section](#next-steps), which has links to guides and samples that will walk you through debugging as well as some common intermediate and advanced topics, like exporting files from the host app, making network requests, and more.



## Contents



- [Technology Used](#technology-used)

- [Prerequisites](#prerequisites)

- [Development Steps](#development-steps)

  - [1. Decide the folder structure](#1-decide-the-folder-structure)

  - [2. Configure Your Extension in `manifest.xml`](#2-configure-your-extension-in-manifestxml)

  - [3. Download `CSInterface.js`](#3-download-csinterfacejs)

  - [4. Write Your Front-end Code](#4-write-your-front-end-code)

    - [Create HTML Markup](#create-html-markup)

    - [Write Your JavaScript Code](#write-your-javascript-code)

  - [5. Write Your ExtendScript Code](#5-write-your-extendscript-code)

  - [6. Launch your extension in the host app](#6-launch-your-extension-in-the-host-app)

- [Next Steps](#next-steps)

- [Other Resources](#other-resources)



## Technology Used

- Supported Host Applications: Photoshop

- Libraries/Frameworks/APIs:

    - Adobe-specific: [CEP](https://github.com/Adobe-CEP/CEP-Resources), [ExtendScript for Photoshop](https://www.adobe.com/devnet/photoshop/scripting.html)



## Prerequisites

Basic knowledge of HTML, CSS, and JavaScript.



## Development Steps



### 1. Decide the folder structure

You will need to decide where to save your extension code first. Your extension can be saved either at the root level or at the user level, depending on who’s allowed to use the extension (refer to [CEP 8 HTML Extension Cookbook](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_8.x/Documentation/CEP%208.0%20HTML%20Extension%20Cookbook.md#extension-folders) for the actual paths).



Except for the required `CSXS` folder, which must contain `manifest.xml`, the folder structure is flexible. One recommended way to structure the folders would be:



![Extension structure](.meta/readme-assets/extension-structure.png?raw=true)



- `/CSXS` -- contains the `manifest.xml` file, which stores the extension configuration data. As noted above, this is a requirement for your extension to show up in the host app.



- `/client` -- contains the front-end HTML, JavaScript, and CSS code, as well as the required Adobe `CSInterface.js` library, and any third-party libraries you might want to include (for example, jQuery).



- `/host` -- contains any ExtendScript files (in this case, `index.jsx`) for your extension. These are used to access and drive most features in the host app



This structure allows you to achieve a clear separation of concerns by devoting one folder to each, client-side and host app.



### 2. Configure Your Extension in `manifest.xml`

There are many possible configurations for this file, but to keep things simple, let’s focus on the minimum requirements (for more, [see the complete version of the manifest, available in the CEP Resources Github repo](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_8.x/ExtensionManifest_v_7_0.xsd)).



For a minimal setup, let's look at the following XML elements and attributes in `manifest.xml`. See the corresponding comments (**#1-7**) in the code that follows:



1. **ExtensionBundleId**: A unique bundle ID you assign to your extension like `com.my.test`

1. **Extension Id**: A unique ID you assign to your extension. It usually follows this syntax: `ExtensionBundleID` + `.panel` = `com.my.test.panel` (note that this ID appears _twice_ in the manifest)

1. **Host Name & Version**: List of host application IDs and versions that your extension is built to support. To learn more, take a look at the [Adobe CEP HTML Extension Cookbook](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_8.x/Documentation/CEP%208.0%20HTML%20Extension%20Cookbook.md#applications-integrated-with-cep)

1. **MainPath**: Path to your `index.html`. Make sure the path to this file is from the top level directory of your code base

1. **ScriptPath**: Path to your `index.jsx`. Make sure the path to this file is from the top level directory of your code base

1. **Menu**: Your extension name that will appear in the dropdown menu of the host app(s)

1. **Size**: Default size of your extension



```xml



  

    

    

  

  

    

      

      

      

    

    

      

    

    

      

    

  

  

    

    

      

        

          

          ./client/index.html

          

          ./host/index.jsx

          

        

        

          true

        

        

          Panel

          

          My First Panel

          

            

              

              500

              350

            

          

          

        

      

    

  



```



This particular configuration gives an panel-type extension called "My First Panel" that supports Photoshop v19 and shows at 500px x 350px.



### 3. Download `CSInterface.js`

You need to download the latest version of [CEP's `CSInterface.js` library](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_8.x/CSInterface.js), which enables you to control the extension and communicate with the application.



You can include this library wherever you like within your codebase, as long as you include it as a `` dependency in your `index.html` file.



If you're following along with this example, place the downloaded `CSInterface.js` directly under `/client`.



### 4. Write Your Front-end Code

Now, it’s time for you to start using your web development skills to build your extension. You can build this out with HTML, CSS, and JavaScript to suit your goals, but let’s have a look at the basic files.



#### Create HTML Markup

The user interface for CEP extensions is written in HTML. For this example, locate the HTML document at `/client/index.html` and write the following code (see comments **#1-3**):



```html

<!DOCTYPE html>

<html>

<head>

    <meta charset="utf-8">

    <title>Your First Panel</title>

</head>

<body>

    <!-- 1) Simple HTML UI elements to get us started -->

    <h1>Your first panel</h1>



    <!-- 2) A button -->

    <button id="open-button">Open</button>



    <!-- 3) Add your script dependencies here, including CEP's CSInterface.js library -->

    <script type="text/javascript" src="CSInterface.js">