Starting Photoshop HTML5 Extension development
The guide Adobe forgot to do!
You’ve had a great idea for a Photoshop extension and you can write Javascript so a quick Google around and you’d expect to find a simple starting guide. No such luck! Documentation is dreadfully fragmented across blog posts, forum threads and visiting Adobe’s Photoshop devnet pages following the obvious choice Learn more about developing for Photoshop takes you to a very uninspiring 404. There appears to be no consolidated overview of how to get started with extensions in general and HTML5 extensions in particular.
[Update — much thanks to Hallgrimur Bjornsson who has provided links to several great resources on the subject: http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/devnet/cs-extension-builder/pdfs/CC_Extension_SDK.pdf, http://www.adobe.com/devnet/creativesuite/articles/a-short-guide-to-HTML5-extensions.html and http://www.davidebarranca.com/category/code/html-panels/]
After trawling the web and a few failed attempts I eventually found that you can now write HTML5 extensions for Photoshop relatively simply.
In response to my frustration at finding information I’ve written this post. In this post I briefly cover what you need to download to get started with HTML5 extension development in Photoshop. Later on we’ll look at debugging and how to execute your Javascript to manipulate the Photoshop document.The post is meant as a beginners guide only but is also attempting to fill in some of the gaps left in the introductory videos posted by Adobe.
I haven’t written anything on releasing your extension as I’m not there yet myself but I’ll be sure to post once I know more.
You can find my code examples on Github: https://github.com/hallodom/photoshop-extension-example
A good introduction
I found this video that was worth watching by Adobe Evangelist Michaël Chaize. He presents a very simple Javascript based panel extension for exporting the current document as a PNG or JPEG and shows you how to build a panel UI via Adobe Configurator 4. Take a little time to watch this video to get an idea of how to interact with the Photoshop document and to see the kinds of things that are possible with Javascript.
Michaël’s tutorial helps you understand some of the process and how easy it is to get started with Javascript based extensions but doesn’t cover HTML5 extensions themselves.
Photoshop HTML5 extensions
The Adobe Configurator is not used for HTML5 extension UI. We can forget the Adobe Configurator altogether. We instead use HTML and CSS to create our panel UI. There’s a blog post I found that is duplicated across Adobe blogs and forums that gives a brief overview: http://blogs.adobe.com/cssdk/2013/09/introducing-html5-extensions.html. The first thing you’ll need is Eclipse installed in order to install and run the Adobe Extension Builder 3 plugin which has everything we need to get started.
Installing the Eclipse plugin
Download Adobe Extension Builder 3, currently in preview at Adobe Labs. This is an Eclipse plugin that gives you a foundation application to build on.
Install the plugin by going to Help > Install New Software… > Add.. > Archive.. select the Adobe Extension Builder zip file > then select the Adobe Extension Builder 3 plugin and install as usual.
Starting a new Photoshop extension project
To make a new extension go to New > Other > Application Extension Project
The example extension provided is a simple ‘hello world’ application. You can see your familiar setup with CSS file and Javascript links. It’s worth mentioning here that I’ve only been using Eclipse to run the extension. I’ve been editing the code inside my preferred text editor Sublime Text.
To run the extension click on the green play button in the top toolbar. This will build the extension and open Photoshop if it’s not already running. To see the extension, in Photoshop go to Window > extension > example (example is the name I chose for this project).
Clicking the ‘Run ps code’ button shows a simple ‘Hello Photoshop’ alert dialog. It’s that simple!
Debugging your HTML5 Photoshop extension
You can run the extension in debug mode from Eclipse which will popup a Chrome like dev tools window you can crawl the HTML DOM and make use of the console.
Unfortunately the dev tools appears to be fairly buggy and often will just disappear. It’s useful to include a button on your panel that you can click to show the dev tools when you need them via this line:
<button onClick=”__adobe_cep__.showDevTools()”>Show DevTools</button>Going deeper
So we have ran our first Photoshop application but looking through the source code it isn’t immediately obvious what’s going on.
In the index.html we can see our <button> element has an onclick event that calls onClickButton(‘PHXS’). If we search for this function in our folders we’ll find it defined in ext.js.
The thing to note here is the evalScript() function :
It’s the CSInterface.evalScript() function that allows our Javascript to access and manipulate the Photoshop DOM by evaluating our script passed in as a string inside the scope of the Photoshop document. All the function onClickButton() is doing is acting as a wrapper to execute the .run() function bound to the ‘PHXS’ object found in the Photoshop.jsx file that comes with the example.
Only by using the CSInterface.evalScript() function can we manipulate layers, access the Photoshop document properties etc. Instead of using onClickButton we can use the evalScript() function directly as it’s defined globally in ext.js which we cover next.
Creating a new Photoshop document with Javascript
As a really simple example we’ll create a new Photoshop document using Javascript. We’ll need to add a button to our index.html:
<li><button id="new-doc">Create New document</button></li>Then bind to the click event using JQuery inside document ready (yes we can use all our favourite libraries here!):
$('#new-doc').on('click',function(e) {
docName = "myDocument";
exec = 'documents.add(800, 500, 72, "' + docName +'")';
evalScript(exec);
});You can see parameters of width, height, resolution and document name. Then we execute our string of Javascript using evalScript(). You can use JSON do deal with more complex objects, see http://www.adobe.com/devnet/creativesuite/articles/introducing-html5-extensions.html
See my code example on Github: https://github.com/hallodom/photoshop-extension-example
Now close Photoshop and press run again in Eclipse. Open our example panel and clicking the ‘Create New Document’ button will create a new document in Photoshop!
Conclusion
This is a very brief introduction but I thought it might be useful for people just starting out. Feel free to comment, correct or ask questions.
Adobe are dropping support for Flash based extensions in favour of HTML5. HTML5 is the future of extension development for the Adobe suite. Although documentation is hard to find it will (I hope) get better to support the growing community.
Some useful links
Some PDF’s on Photoshop scripting and documentation around the classes available to manipluate the Photoshop document: http://www.adobe.com/devnet/photoshop/scripting.html
Adobe’s introduction to HTML5 extensions:
http://www.adobe.com/devnet/creativesuite/articles/introducing-html5-extensions.html
Photoshop Extension Builder 3 forum, these guys are really helpful! You’ll need an account to get going.
http://forums.adobe.com/community/labs/extensionbuilder3
Code example: https://github.com/hallodom/photoshop-extension-example
