{"id":18290121,"url":"https://github.com/adobe-cep/getting-started-guides","last_synced_at":"2025-05-15T11:07:10.404Z","repository":{"id":41390310,"uuid":"128245822","full_name":"Adobe-CEP/Getting-Started-guides","owner":"Adobe-CEP","description":"Getting Started guides and samples for CEP extensions","archived":false,"fork":false,"pushed_at":"2025-03-19T18:29:23.000Z","size":14647,"stargazers_count":592,"open_issues_count":19,"forks_count":93,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-04-14T18:13:34.072Z","etag":null,"topics":["cep","cep-extension","extendscript","html","illustrator","indesign","javascript","photoshop"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Adobe-CEP.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-05T18:12:44.000Z","updated_at":"2025-04-14T02:11:39.000Z","dependencies_parsed_at":"2024-11-21T13:11:28.829Z","dependency_job_id":"6984a8fd-1d3e-4ae4-b45b-12ac666e2580","html_url":"https://github.com/Adobe-CEP/Getting-Started-guides","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adobe-CEP%2FGetting-Started-guides","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adobe-CEP%2FGetting-Started-guides/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adobe-CEP%2FGetting-Started-guides/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adobe-CEP%2FGetting-Started-guides/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Adobe-CEP","download_url":"https://codeload.github.com/Adobe-CEP/Getting-Started-guides/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248933340,"owners_count":21185460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cep","cep-extension","extendscript","html","illustrator","indesign","javascript","photoshop"],"created_at":"2024-11-05T14:09:35.492Z","updated_at":"2025-04-14T18:13:38.372Z","avatar_url":"https://github.com/Adobe-CEP.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Getting Started with CEP Extensions\n\nCEP (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.\n\nIn this guide, we will help you quickly get started building a CEP extension by covering the basics in 6 easy steps.\n\nBy the end of this guide, we will have a CEP extension that opens a new document from the user's local folder.\n\n![Example extension: opening a new file in Photoshop](.meta/readme-assets/extension.gif?raw=true)\n\nWhen 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.\n\n\u003c!-- doctoc command config: --\u003e\n\u003c!-- $ doctoc ./readme.md --title \"## Contents\" --entryprefix 1. --gitlab --maxlevel 3 --\u003e\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n## Contents\n\n- [Technology Used](#technology-used)\n- [Prerequisites](#prerequisites)\n- [Development Steps](#development-steps)\n  - [1. Decide the folder structure](#1-decide-the-folder-structure)\n  - [2. Configure Your Extension in `manifest.xml`](#2-configure-your-extension-in-manifestxml)\n  - [3. Download `CSInterface.js`](#3-download-csinterfacejs)\n  - [4. Write Your Front-end Code](#4-write-your-front-end-code)\n    - [Create HTML Markup](#create-html-markup)\n    - [Write Your JavaScript Code](#write-your-javascript-code)\n  - [5. Write Your ExtendScript Code](#5-write-your-extendscript-code)\n  - [6. Launch your extension in the host app](#6-launch-your-extension-in-the-host-app)\n- [Next Steps](#next-steps)\n- [Other Resources](#other-resources)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Technology Used\n- Supported Host Applications: Photoshop\n- Libraries/Frameworks/APIs:\n    - Adobe-specific: [CEP](https://github.com/Adobe-CEP/CEP-Resources), [ExtendScript for Photoshop](https://www.adobe.com/devnet/photoshop/scripting.html)\n\n\n## Prerequisites\nBasic knowledge of HTML, CSS, and JavaScript.\n\n\n## Development Steps\n\n### 1. Decide the folder structure\nYou 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).\n\nExcept for the required `CSXS` folder, which must contain `manifest.xml`, the folder structure is flexible. One recommended way to structure the folders would be:\n\n![Extension structure](.meta/readme-assets/extension-structure.png?raw=true)\n\n- `/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.\n\n- `/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).\n\n- `/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\n\nThis structure allows you to achieve a clear separation of concerns by devoting one folder to each, client-side and host app.\n\n\n### 2. Configure Your Extension in `manifest.xml`\nThere 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)).\n\nFor 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:\n\n1. **ExtensionBundleId**: A unique bundle ID you assign to your extension like `com.my.test`\n1. **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)\n1. **Host Name \u0026 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)\n1. **MainPath**: Path to your `index.html`. Make sure the path to this file is from the top level directory of your code base\n1. **ScriptPath**: Path to your `index.jsx`. Make sure the path to this file is from the top level directory of your code base\n1. **Menu**: Your extension name that will appear in the dropdown menu of the host app(s)\n1. **Size**: Default size of your extension\n\n```xml\n\u003c?xml version='1.0' encoding='UTF-8'?\u003e\n\u003c!-- 1) --\u003e\n\u003cExtensionManifest ExtensionBundleId=\"com.my.test\" ExtensionBundleVersion=\"1.0.0\" Version=\"7.0\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\u003e\n  \u003cExtensionList\u003e\n    \u003c!-- 2) --\u003e\n    \u003cExtension Id=\"com.my.test.panel\" Version=\"1.0.0\" /\u003e\n  \u003c/ExtensionList\u003e\n  \u003cExecutionEnvironment\u003e\n    \u003cHostList\u003e\n      \u003c!-- 3) --\u003e\n      \u003cHost Name=\"PHSP\" Version=\"19\" /\u003e\n      \u003cHost Name=\"PHXS\" Version=\"19\" /\u003e\n    \u003c/HostList\u003e\n    \u003cLocaleList\u003e\n      \u003cLocale Code=\"All\" /\u003e\n    \u003c/LocaleList\u003e\n    \u003cRequiredRuntimeList\u003e\n      \u003cRequiredRuntime Name=\"CSXS\" Version=\"7.0\" /\u003e\n    \u003c/RequiredRuntimeList\u003e\n  \u003c/ExecutionEnvironment\u003e\n  \u003cDispatchInfoList\u003e\n    \u003c!-- 2) --\u003e\n    \u003cExtension Id=\"com.my.test.panel\"\u003e\n      \u003cDispatchInfo\u003e\n        \u003cResources\u003e\n          \u003c!-- 4) --\u003e\n          \u003cMainPath\u003e./client/index.html\u003c/MainPath\u003e\n          \u003c!-- 5) --\u003e\n          \u003cScriptPath\u003e./host/index.jsx\u003c/ScriptPath\u003e\n          \u003cCEFCommandLine /\u003e\n        \u003c/Resources\u003e\n        \u003cLifecycle\u003e\n          \u003cAutoVisible\u003etrue\u003c/AutoVisible\u003e\n        \u003c/Lifecycle\u003e\n        \u003cUI\u003e\n          \u003cType\u003ePanel\u003c/Type\u003e\n          \u003c!-- 6) --\u003e\n          \u003cMenu\u003eMy First Panel\u003c/Menu\u003e\n          \u003cGeometry\u003e\n            \u003cSize\u003e\n              \u003c!-- 7) --\u003e\n              \u003cHeight\u003e500\u003c/Height\u003e\n              \u003cWidth\u003e350\u003c/Width\u003e\n            \u003c/Size\u003e\n          \u003c/Geometry\u003e\n          \u003cIcons /\u003e\n        \u003c/UI\u003e\n      \u003c/DispatchInfo\u003e\n    \u003c/Extension\u003e\n  \u003c/DispatchInfoList\u003e\n\u003c/ExtensionManifest\u003e\n```\n\nThis particular configuration gives an panel-type extension called \"My First Panel\" that supports Photoshop v19 and shows at 500px x 350px.\n\n### 3. Download `CSInterface.js`\nYou 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.\n\nYou can include this library wherever you like within your codebase, as long as you include it as a `\u003cscript\u003e` dependency in your `index.html` file.\n\nIf you're following along with this example, place the downloaded `CSInterface.js` directly under `/client`.\n\n### 4. Write Your Front-end Code\nNow, 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.\n\n#### Create HTML Markup\nThe 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**):\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003ctitle\u003eYour First Panel\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003c!-- 1) Simple HTML UI elements to get us started --\u003e\n    \u003ch1\u003eYour first panel\u003c/h1\u003e\n\n    \u003c!-- 2) A button --\u003e\n    \u003cbutton id=\"open-button\"\u003eOpen\u003c/button\u003e\n\n    \u003c!-- 3) Add your script dependencies here, including CEP's CSInterface.js library --\u003e\n    \u003cscript type=\"text/javascript\" src=\"CSInterface.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\" src=\"index.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nAs can been seen in the code above, the `CSInterface.js` library is included as a `\u003cscript\u003e` dependency in this `index.html` file.\n\n\n#### Write Your JavaScript Code\nMake sure to create an instance of `CSInterface`. Your `CSInterface` instance will give you access to methods and properties useful for buildling your extension.\n\nOne of those methods, `evalScript()`, will let you communicate from your client-side JavaScript to your ExtendScript code (ExtendScript is covered in the next section) and back. See comments **#1-3**:\n\n```javascript\n/* 1) Create an instance of CSInterface. */\nvar csInterface = new CSInterface();\n\n/* 2) Make a reference to your HTML button and add a click handler. */\nvar openButton = document.querySelector(\"#open-button\");\nopenButton.addEventListener(\"click\", openDoc);\n\n/* 3) Write a helper function to pass instructions to the ExtendScript side. */\nfunction openDoc() {\n  csInterface.evalScript(\"openDocument()\");\n}\n```\n\nFeel free to refer to [the CEP Github repo](https://github.com/Adobe-CEP/CEP-Resources) if you are curious about what else you can do with `CSInterface`.\n\n### 5. Write Your ExtendScript Code\nExtendScript code is different from your client-side JavaScript in that, via ExtendScript, you can access the host application’s functionalities, such as opening a document, editing it, exporting it, and almost anything else the host application can do.\n\nIn this example, we will create a function that opens one file in the host application. Make sure to change the file name and the path to a file that actually exists in your filesystem.\n\n```javascript\nfunction openDocument(){\n  var fileRef = new File(\"~/Downloads/myFile.jpg\");\n  var docRef = app.open(fileRef);\n}\n```\n\nThis `openDocument()` helper function will be called when `csInterface.evalScript(\"openDocument()\")` is invoked from your client-side JavaScript file.\n\n### 6. Launch your extension in the host app\nWhere the user can find and open your extension will depend on the Creative Cloud host app that your extension supports.\n\nSince the sample extension we made in this guide supports Photoshop, you can find the extension under:\n\n\u003e Window \u003e Extensions \u003e My First Panel\n\nWhen you try to launch your extension, if you get an alert about unsigned extensions, see the [\"Set the Debug Mode\" section](Client-side%20Debugging/readme.md#set-the-debug-mode) of our Client-side debugging guide.\n\n\n## Next Steps\n\nNow that you've seen the basics, check out these guides and samples that walk you through some common intermediate and advanced topics in CEP:\n\n- [Client-side debugging](Client-side%20Debugging)\n- [Package Distribute Install](Package%20Distribute%20Install)\n- [Exporting files from the host app](Exporting%20files%20from%20the%20host%20app)\n- [Network requests and responses with Fetch](Network%20requests%20and%20responses%20with%20Fetch)\n\n\n## Other Resources\n- [CEP Cookbook](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_8.x/Documentation/CEP%208.0%20HTML%20Extension%20Cookbook.md)\n- [CEP Samples repo](https://github.com/Adobe-CEP/Samples)\n- [Adobe Photoshop Reference Doc](https://www.adobe.com/devnet/photoshop/scripting.html)\n- [Adobe Illustrator Reference Doc](https://wwwimages2.adobe.com/content/dam/acom/en/devnet/illustrator/pdf/Illustrator_JavaScript_Scripting_Reference_2017.pdf)\n- [InDesign Reference Guide](https://wwwimages2.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/scripting/InDesign_ScriptingGuide_JS.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe-cep%2Fgetting-started-guides","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadobe-cep%2Fgetting-started-guides","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe-cep%2Fgetting-started-guides/lists"}