Photoshop HTML Panels Development Build and Market Adobe Creative Cloud extensions Davide Barranca © 2015 - 2016 Davide Barranca - Adobe® Photoshop® and Adobe® Creative Cloud® are registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners.
FREE EXCERPT! !e following content is a ~40 pages excerpt from the full eBook. !e complete Adobe Photohop HTML Panels Development course contains:
The Book 285 pages PDF, 15 Chapters of solutions to real-world development problems. ePub and Mobi digital versions included. 28 Panels Each Chapter covers a topic, then custom-made Panels (with fully commented code) dig deeper, implementing the basic concepts shown in a more advanced fashion. Three hours HD video series 8 HD screencasts dealing with some of the aspects covered in the book, adding extra information and new sections on specific subjects (such as ActionManager code). Highly recommended to beginners!
The Full Package is available HERE!
To my wife Elena
Contents Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
i
Introduction . . . . . . . . . . . . . . . Why I wrote this book . . . . . . . . Audience and Assumptions . . . . . What this book is, and how to read it What this book is not . . . . . . . . What you need to get started . . . . Version History and Errata . . . . . Feedback . . . . . . . . . . . . . . . Piracy . . . . . . . . . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. iv . iv . v . vi . vii . vii . viii . ix . ix
1. Photoshop Extensibility . Overview . . . . . . . . . Plug-ins (Photoshop SDK) Scripting . . . . . . . . . Flash Panels . . . . . . . HTML Panels . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
1 1 1 2 4 5
2. The HTML Panel Stack . . . . . . . . . . CEP: Common Extensibility Platform . CEF: Chromium Embedded Framework HTML and CSS . . . . . . . . . . . . . Javascript . . . . . . . . . . . . . . . . . Extendscript . . . . . . . . . . . . . . . Layers communication . . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
6 7 7 7 8 8 9
3. Setting up the environment . . . . . . Code editors . . . . . . . . . . . . . . Getting started: setting the Debug Flag Installation folders . . . . . . . . . . . Download the Libraries . . . . . . . . Storing projects . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
10 10 12 13 14 14
4. Building up “Hello World!” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
CONTENTS
Take 1: Manifest.xml Take 2: ExtendScript . Take 3: Debugging . . Hello World wrap-up
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
16 20 24 27
5. CSInterface . . . . . . . . . . . . . . . . . . JS interface . . . . . . . . . . . . . . . . . . CEP Versions . . . . . . . . . . . . . . . . . evalScript() . . . . . . . . . . . . . . . . . . getSystemPath() and including multiple JSX
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
28 28 31 33 37
6. Exchanging data between Panel and Host Application Passing primitive values from JS to JSX . . . . . . . . Passing Objects from JS to JSX . . . . . . . . . . . . . Passing Objects from JSX to JS . . . . . . . . . . . . . Demo Panel: actions . . . . . . . . . . . . . . . . . . . Demo Panel: Data exchange . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
42 42 43 45 48 50
7. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . No shortage of Events in town . . . . . . . . . . . . . . . . Host Application Events - ExtendScript Events in Photoshop Host Application Events - CEP Application Events . . . . . Custom ExtendScript Events . . . . . . . . . . . . . . . . . Custom CEP Events . . . . . . . . . . . . . . . . . . . . . . CEP Panel’s Events . . . . . . . . . . . . . . . . . . . . . . Demo Panel: Photoshop ExtendScript Events . . . . . . . . Demo Panel: Photoshop CEP Events (LoseFocus) . . . . . . Demo Panel: Photoshop Custom ExtendScript Events . . . . Demo Panel: CEP Custom Events . . . . . . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
56 56 57 63 67 69 70 70 72 73 75
8. Styling . . . . . . . . . . . . . . . . . . . . . Matching the Host Application UI look . . . Synch with Photoshop Theme changes . . . Flyout and Contextual menus . . . . . . . . Icons, Size and Retina Displays . . . . . . . Demo Panel: Flyout and Contextual menus Demo Panel: High PPI display . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
80 80 84 89 91 94 99
9. Node.js . . . . . . . . . . . . . . . . . . . . . . . . Two of a kind . . . . . . . . . . . . . . . . . . . Importing modules . . . . . . . . . . . . . . . . . Issues and Workarounds . . . . . . . . . . . . . . Demo Panel: connecting to a REST service . . . . Demo Panel: modularize JSX Events management
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
103 103 104 106 109 114
CONTENTS
10. Store and retrieve Data locally . . . . . . Persistence . . . . . . . . . . . . . . . . . Using the Filesystem . . . . . . . . . . . . Web Storage . . . . . . . . . . . . . . . . IndexedDB . . . . . . . . . . . . . . . . . Which one should I use? . . . . . . . . . . Demo Panel: Persistence . . . . . . . . . . Demo Panel: Node fs and nconf modules Demo Panel: Node.js presets module . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
121 121 122 130 132 136 136 138 140
11. Javascript Frameworks . . . . . . . . . . . . . . What is the best JS framework for HTML Panels? Newbies corner . . . . . . . . . . . . . . . . . . Demo Panel: Angular JS . . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
151 151 153 154
12. Communicate with the WWW . . . . . . Connect with the internet . . . . . . . . . Download and open a file . . . . . . . . . Upload a file . . . . . . . . . . . . . . . . Downloading and Uploading with Node.js Local Node.js servers . . . . . . . . . . . Operating PS remotely . . . . . . . . . . . CORS: PostMessage and WebSockets . . . Generator integration . . . . . . . . . . . Demo Panel: Flickr . . . . . . . . . . . . . Demo Panel: Upload (XMLHttpRequest) . Demo Panel: Master / Slave . . . . . . . . Demo Panel: No-CORS and postMessage . Demo Panel: Socket.io . . . . . . . . . . . Demo Panel: Generator server . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
165 165 166 168 171 172 172 175 179 183 186 193 200 202 206
13. Miscellanea . . . . . . . . . . . . . . . . . . . . . . . CEP - The other API . . . . . . . . . . . . . . . . . . Inter-application communication (with Demo Panel) Extensions types . . . . . . . . . . . . . . . . . . . . CEF command parameters . . . . . . . . . . . . . . Localization (with Demo Panel) . . . . . . . . . . . . Panel Licensing . . . . . . . . . . . . . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
212 212 215 219 221 221 224
14. Packaging and Distributing . . . . . . . . . Signing and Timestamping . . . . . . . . . . Certificates . . . . . . . . . . . . . . . . . . . Using the ZXPSignCMD commandline utility Hybrid Extensions . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
227 227 228 230 233
. . . . . . . . . . . . . . .
. . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . .
. . . . . . . . . . . . . . .
. . . . .
. . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
CONTENTS
Supporting older versions . . . . . . . . . . . . . . . . . . . . . Advanced automation with Gulp . . . . . . . . . . . . . . . . . Distributing, or the Art of minimizing Customer Support emails Manual installation . . . . . . . . . . . . . . . . . . . . . . . . Adobe Add-ons . . . . . . . . . . . . . . . . . . . . . . . . . . Adobe Extension Manager CLI . . . . . . . . . . . . . . . . . . Third-party free ZXP installers . . . . . . . . . . . . . . . . . . PS Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15. The Extensions Business . . . Software is boring . . . . . . . Pricing . . . . . . . . . . . . . Marketplaces . . . . . . . . . . Your own storefront . . . . . . Payment services . . . . . . . . Pricing (revisited) . . . . . . . Looking after your Customers Conclusions . . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
237 239 248 248 249 252 253 254 255
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
257 257 257 260 264 265 268 268 270
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Foreword We are all aware of the possibilities of automating and expanding the functionality of Adobe applications. Many people, surely, would like to learn the art of programming, so as to add such functionality, to make their workflow more productive and adapted to their personal needs. Now that we can create Extensions for Creative Cloud applications, all this has been made possible. Adobe Configurator, although misunderstood throughout its life, was the tool that allowed even the less experienced to approach this magical world. Its removal from the scene has limited such access to programmers, who can only navigate the process of creating Panels and Extensions in the new HTML format with great difficulty, owing to the lack of adequate documentation. Of course, nothing is difficult for programmers with considerable experience or a great aptitude for the subject. Thanks to the talented Davide Barranca, who combines both attributes, we are now fortunate enough to have a complete and comprehensive guide. He has learned everything in the field with steady work, passion, dedication and many headaches! For this reason, his work really needs no introduction, guarantees, or recommendations. A quick trip to the web will demonstrate his capabilities, the quality and professionalism of his work and the support he has given to the entire developer community. His blog has quickly gone viral and has offered solutions and information valuable both to neophytes and the most experienced. I have known Davide since his first forays into this field. What distinguishes him is his constant study, his perseverance in the search for solutions, and the tenacity with which he deepens every aspect of programming. The difficulty of obtaining information and the sudden changes in requirements caused many, albeit reluctantly, to abandon the development of extensions. To say nothing of the beginners who did not enter the field for fear of being stranded on a desert island! Like a boat in a fierce storm, or in a minefield, those who are not well equipped and aware of the problems they face risk being shipwrecked. The solution is training, and the exchange of information and experiences. The interchange of ideas, the sharing of a project, the grasping of a new technique, is much easier in a collaborative environment. Learning what others have experienced, and sharing common problems, is often the easiest path, assuming that colleagues share the same goals. But how do we overcome the lack of information? Special-interest online discussion groups are today’s equivalent of that collaborative environment. They are places where neophytes and experts can each find complete responses and partial solutions to their problems. Google searches, blogs and private sites of independent developers, open source communities such as the social network GitHub can also be quite useful for tapping into resources, collaborating on a project, and/or putting information at the disposition of the community. So, despite all the difficulties, there is some sharing of this ocean of knowledge. i
Foreword
ii
We must therefore know how to glean the exact information needed for our specific needs, to find the one best suited to our particular problem. And time is also a factor: it is essential to get quick answers, so as to concentrate more on the real problems instead of spending whole days in research, and ending up with a fistful of nothing. It can be an exasperating experience that in most cases yields only partial answers. And the information on how to create an HTML extension is as fragmented as it could possibly be. There is no one place to find all the explanations and the assembly of concepts, and the search for it is likely to be frustrating and debilitating. What is lacking is a place where experts and novices can find everything needed for a proper and rapid development, allowing free rein to creativity and inventiveness. This material, however, gets us only halfway there, since in most cases the transition from theory to practice does not occur without problems. The rest of the process depends on our own energy and capacity. But where can we find the correct, complete, exhaustive and effective presentation of the basic material? For me there is no doubt, it is right here in the pages of this book. Davide has supplied the missing link, the manual that each type of developer needs. Like the NeverNeverland of Peter Pan, it is a place to discover yourself and explore your own passions and resolve your own difficulties. He has put his knowledge and experience at our disposal without reserve, not just to put us in a position to execute our projects but also to recognize pitfalls. The book is rich in advice and tricks to get around obstacles and avoid confrontations with the evils that inevitably lurk around the corner. Every successful enterprise is the fruit of great work and great passion. Thanks to Davide’s extraordinary teaching abilities, Photoshop HTML Panels Development leads the reader down a stable and well-defined path. You will be taken step by step, with effective examples and clear concepts, from a comprehension of the terminology, to a knowledge of the architecture on which the extensions are based, to the completion of commercially ready products, and finally to the considerations of how to market them. Above all, you will learn to comprehend the reasons and concepts behind each step, and thus to achieve the autonomy to develop and create your own extension. Adding to the completeness of the information, Davide has made all the resources available on the web. Photoshop HTML Panels Development is a book suitable for everyone. The beginner will find it a great way to start, but even top experts will discover new and useful resources. To the great envy of many, I was lucky enough to read this book during all stages of its drafting. I myself have discovered ways to integrate and take advantage of new and interesting features, which allowed me to bring to life certain older projects that were in an embryonic state because I had not been able to overcome various problems by myself. Davide’s demonstrations and explanations will be equally valuable for whatever my next projects may be. I am sure that this book is well worth whatever time you spend on it. As for money, a friend once told me that one should find at least five good reasons before spending it. I agree, and here are some of mine.
Foreword
iii
1. It lets me compare my work with that of another experienced programmer. 2. It offers new ideas and shows how to apply, with minimal effort, new and unexplored techniques. 3. It is a compendium of resources that can be accessed very quickly. 4. The subject of this book is indispensable to my library, it is also the only one that comes to HTML development panels. 5. There are possibilities to expand and possibly customize solutions that I have already found. I could easily name more than five reasons but I think these are by far sufficient. I just want to add a note for all of those who have asked me where to start in this field. The answer is now official. Without this book will be a long and uphill road. It is not hard to predict the question that comes spontaneously to your mind at this time. Why should I pay any attention to the words of Giuliana Abbiati? Who is she, and what has she ever done to qualify her to give me such advice? I am perhaps the wrong person to ask this of, but I will give you an answer anyway. I could be any one of you. Titles have little importance in my opinion. They do not always guarantee objectivity. What is certain is that I have seen every problem involving the creation of panels and extensions, and if I had had a book like this at my disposal it would have saved me from a thousand moments of despair and dozens of unnecessary tests. I believe that the same would apply to Davide, with whom I have shared such moments. I hold Davide in the highest esteem, and I thank him not only for his work and for the free resources that he has always put at the community’s disposal, but also for flattering me with the opportunity to give my personal opinion about the quality and utility of this his first book, and last but certainly not least for the sincere friendship that has bound us together for many years. And now, the interesting part: Photoshop HTML Panels Development by Davide Barranca. Giuliana Abbiati Author of CPT - Channels Power Tool¹, and Dan Margulis’ PPW Panel² ¹http://www.cs-extensions.com/products/cpt/ ²http://www.moderncolorworkflow.com/free-resources
Introduction Whether you’ve just bought this book or you’re reading here to make sure it fits your needs and level of expertise, welcome to the introduction of Adobe Photoshop HTML Panels Development. This Chapter will shed some light on Creative Cloud Extensions, the reason why they are an interesting coding experience, and a profitable business too.
Why I wrote this book Over the last seven years I’ve been devoting an increasing amount of time to the development of Photoshop Scripts and Panels: either as products of mine to be sold in digital marketplaces, contract jobs for clients, or helping colleagues and people asking for advice in public forums. Photoshop and Creative Cloud Extensions, in general, have been evolving rapidly over time, and documentation has not always been priority number one. Apparently, many people who found themselves stuck with a particular coding issue related to Panels (a frequent fact of life that everybody who’s ever been exposed to Adobe SDKs has a good knowledge of), to my great surprise, have been starting to reach out for my help. And to a possibly even greater surprise of mine, it seems like I’ve been, mostly, successful in providing them with guidance, reference code, or simply my unopinionated point of view. Photoshop and Creative Cloud Extensions are, as far as I understand them, largely a matter of experience - e.g. avoiding common pitfalls or knowing best practices - in many cases I’ve just been there before, I’ve seen how things evolved from the very beginning. Also, the learning curve involves such a large variety of subjects that is hard for the newcomer (and everyone else as well) to focus on the many Panels’ facets and the bigger plan at the same time. This book is going to save you many hours of unrewarding head-scratching time and frustration which I’ve a huge personal collection of around the house - the main goal is to give you a substantial productivity head start. Over time I’ve found a way to take advantage of Photoshop extensions to make a profitable and selfsustaining side-business. To date, I’ve built and marketed four paid products of mine, plus additional five in collaboration with other developers - for sale in several, different e-stores - not to mention free and open-source stuff. Now, 40% of my total incomes as a Photoshop freelance is not time-based (e.g. working with photographers doing post-production on hourly fees) and comes as monthly payments from software vendors. Besides, programming didn’t eat away at my daytime job - I’ve been able to maintain and grow my software business working when my usual Photoshop clients let me free, mostly on weekends and by night. There are better ways to run this kind of trade, but here I am to prove that iv
Introduction
v
Extensions can be turned into a profitable venture: the more you invest on it, the better the yield, of course. This book has been written to show you how I’ve been doing it.
Audience and Assumptions It’s really important for me that your expectations, as a reader of this book, are met. On your side, to exploit its value you must evaluate first whether it’s a good fit for your needs, skills and mindset - because delusion most of the times is just a mismatched expectations’ by-product. I do not want this course to be bought by everyone vaguely interested in HTML Panels development; you do not want your time to be wasted on something that is not going to provide you with a tangible profit. So please read along. The title I’ve chosen is Adobe Photoshop HTML Panels Development for a reason - the software I’ve fed my family thanks to, in the last 16 years, is Photoshop. Yet Panels structure and features are largely shared among the whole lineup of Adobe’s Creative Cloud applications supporting HTML Panels: • • • • • • • • •
Photoshop InDesign InCopy Illustrator Premiere Pro After Effects Prelude Flash Pro Dreamweaver
Excluding some Event-specific parts, I’d say that most if not all of the code shown in this book, and the whole marketing section, apply to any other Creative Cloud app mentioned above - which has been corroborated by beta readers who work on InDesign and Illustrator - so you’re going to make good use of this book even if your main focus is not on Photoshop. HTML Panels are Web Applications hosted inside, and communicating with, Adobe Creative Cloud apps. As a developer, you’ll be writing code related to the Panel’s functionality (using the HTML + CSS + JS stack) and code related to the Host Application operations (Photoshop Scripting, InDesign Scripting, etc. that is, ExtendScript language). If you are totally new to whichever form of coding, I’m afraid this book would be a waste of time and money: I’d suggest you to take one of the many available free or paid courses on Web Development first. Enjoy that stack? Come back here and you’ll find new challenges.
Introduction
vi
If you have an Adobe Configurator background and/or a very basic Javascript / ExtendScript experience you’ll probably be OK until Chapter 6, that brings you to the point where you know how build HTML Panels calling Actions in ActionSets, which is what a large majority of former Configurator users are after. However, it won’t be the kind of book that you can skim through, picking here and there and jumping to the Demo code straight away. If you’re looking for that kind of thing, my friendly bit of advice is to look elsewhere. From Chapter 7 onwards, you’ll definitely need supplementary, supporting material alongside this book, like dedicated CSS / JS / Node.js courses, otherwise you won’t be able to retain and make the most of what is shown there - and it’s alot. Mind you I don’t want to sound discouraging, but realistic: a path from the average Configurator user to the average HTML Panels developer is indeed possible, and this book has been written also for you. It just requires planning and extra resources, there’s no reason for me to skate over this and allure you with copywriting tricks. If you come from good old Photoshop scripting (that’s my own background, so I’m sympathetic), I assume that you have a fine grasp of ExtendScript - which is nothing but a Javascript superset. HTML Panels for sure have their own quirks, but you can definitely enjoy the process of learning how to build them. Get ready to pay frequent visits to StackOverflow and the Mozilla DevNet, since Web Development is the kind of tree that branches up to the stratosphere and beyond; luckily, if you want to go into it in more depth, there’s no shortage of resources on the internet. Conversely, if you are a Web Developer willing to exploit the power of Adobe Creative Cloud applications, you’ll get easily into the part of the HTML Panel builder: Photoshop scripting will look quite convoluted at first, but you’re going to get used to that in a reasonable amount of time. In case you’re the King of the Keyboard and you know Photoshop like the back of your hand, please have my seat and enjoy the ride.
What this book is, and how to read it A couple of years ago a friend of mine, who happens to be a very talented Photoshop retoucher in Milan, Italy, called me asking to meet for a few hours: “I need to get started with extensions! You show me the basics, the pitfalls, documentation plus a list of reference links, and then I’ll carry on with it myself”. Which in theory makes sense - but as they say: “In theory, theory and practice are the same, but in practice… they’re not”. This book aims to provide you with an extended, thorough answer to my friend’s ambitious yet optimistic inquiry. I will introduce you to the topic of Photoshop and Creative Cloud panels: what they are made of; what they are for; what they are not for. I’ll show you their architecture and inner working - how Extensions are built and debugged, how to use JS a framework, how to access Node.js modules, how to connect with a server, etc. The book is also a hands-on reference for a large number of specific needs (which I know are very common because I see them pop in my Mail’s InBox), by examples: the way Panels deal with the host when it comes to app-specific Events, how to save mutable data or successfully sign and timestamp a product for submission to the Adobe Add-ons or other stores, etc.
Introduction
vii
Moreover, it is a collection of personal researches on the topic of Photoshop panels, countless hours spent dealing with experienced people on forums, blogging, submitting bugs and feature requests to, and discussing them with, Adobe’s engineers. Adobe Photoshop HTML Panels Development is a tool that will give you an invaluable productivity head start, equipping you with an arsenal of tested and proven work solutions to the problem of building and marketing Photoshop and Creative Cloud panels - that I put in practice myself running my own daily business as an Extensions producer. Especially If you’re green on development, I urge you to read it from start to finish, because it’s been designed to slowly build up your skills: each chapter is a prerequisite of the one that follows, and uses tools and knowledge coming from previous sections. The book also contains 28 Demo Panels, a true bonanza! Don’t skim through the writing to focus just on code, though: they usually are a more elaborate example of what’s been discussed during the chapter, and without a solid understanding of the basics that have been laid out in the text, you’re going to loose a lot of their potential learning value.
What this book is not This is not “HTML Extensions Cookbook: 42 ready-made Panels to borrow code from”, nor “Learn Photoshop Panels in 12 days and 4 full projects”. I will be providing you with descriptions, recipes and lot of code samples as well, but my approach is different from Cookbooks and Project Books. It’s a vast topic and I prefer to be more systematic - furthermore, I like to introduce concepts first, then discuss the implementation, and eventually show my interpretation (which is just my take, not code set in stone). This material requires some squeezing of the brain juices also because, when it comes to OCOSA³, Adobe’s HTML Panels are second to none.
What you need to get started Coding Panels is now way more affordable than it used to be in the past when I started, and Flash, as opposed to HTML, was mainstream. Back then, you could access Adobe Extension Builder 1 and 2 (the Eclipse plugins required to build Flash panels⁴) only by subscribing to a paid Adobe Technology Partner Program - mine was Bronze, the cheapest, which included the Extension Builder download as a benefit. Much water has passed under the bridge… Long story short, the Javascript libraries are now free for you to grab on GitHub, so the requirement list shrinks to: ³Office for Complication of Otherwise Simple Affairs. ⁴Which doesn’t mean “panels hosted in Flash Pro”, but “panels coded in ActionScript”.
viii
Introduction
1. A licensed copy of Photoshop CC or newer (CC2014, CC2015, CC2015.5…), or another Creative Cloud app supporting HTML Panels. 2. A good text editor: pick up the one you are already comfortable with, or try: • Sublime Text⁵ (paid) • Adobe Brackets⁶ (free) • Atom⁷ (free) • Microsoft Visual Studio Code⁸ (free and surprisingly available for Windows, Mac and Linux) 3. The ExtendScript ToolKit (aka ESTK), the Adobe script editor: find it in the Creative Cloud downloads). 4. The Google Chrome browser for debugging. 5. Comfort items of your choice. You can develop on both OSX and Windows - I strongly suggest you to test the other platform before submitting your product to marketplaces, since running into platform-specific bugs is not unfrequent. I use Parallels⁹ on a Mac, but different solutions are available. Mind you, running Photoshop in a virtualized OS might require you to deactivate it on a different machine, if you’ve exceeded the number of maximum Creative Cloud activations. Also, be aware that virtualizing software such as VMWare¹⁰ can capture by default modifiers keys (e.g. the meta on Mac), so you may need to remap some of your keyboard shortcuts.
Version History and Errata The book has been written while I was working in Photoshop CC 2015.0.x (CEP6.0), then updated to CC2015.1.x (CEP 6.1) and CC2015.5 (CEP 7.0). Over time Adobe has pushed some changes and/or introduced remarkable differences in the framework, which made my panels sometimes break, sometimes work again: the never boring life of the third party developer. I have fixed my code to comply to the latest available Photoshop version when I judged that appropriate, while I’ve left it as it originally was in all those cases when, in my opinion, it is opportune to wait for a bugfix on Adobe’s side. This icon will signal you that a Panels’ issue has been resolved from a particular Photoshop version onwards, and the code working around that problem has to be intended for backwards compatibility only. Over time, I hope to fill this book with lot of Peace & Love fingers.
⁵http://sublimetext.com ⁶http://brackets.io ⁷https://atom.io ⁸https://code.visualstudio.com ⁹http://parallels.com ¹⁰http://www.vmware.com
Introduction
ix
Version 1.1.0 Second release, July 2016. New: • Adobe Photoshop CC2015.5 (despite what you’d think, a major version: 17.0) has been released June 21st, 2016. CEP has been bumped to version 7.0. I’ve updated all the book, where needed, to cover the new version. • Mentioned Extendscriptr, page 8. • Added cefclient and Chrome Dev Tools scrolling fix, page 26. Fixes: • • • •
Gabe Harbs’ website link (sorry!), page 26. Added a note on “User Cancelled Error” on CC2015/Windows for the Actions panel, page 50. Color in Panel’s icons is in fact allowed, page 89. Typos here and there, minor changes.
Version 1.0.0 First release, March 2016.
Feedback I’d love to hear from you! What is your background, what you’re going to build next, whether you’ve found this book a good fit or not, and why. If you want to share your thoughts, let me know at
[email protected].
Piracy This book is going to be pirated, like most of the published books, magazines and newspapers for sale in the digital world. Some would also say that it’s a good thing, other would raise the “let the one who has never sinned throw the first stone!” argument. Since it’s very likely that you, the reader, have picked this book because you want to build a business on top of Extensions yourself, I am confident that you have paid, or will very soon pay, to obtain a legitimate copy and repay my efforts. Because if you’re successful in building HTML Panels, you’ll be in my own shoes yourself - very soon - and you don’t want this to happen to you to, do you? Thank you.
1. Photoshop Extensibility “In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move.” -Douglas Adams
Overview Let’s have a look at the bouquet of options you have as a Photoshop developer - HTML Panels are not the only choice, and you might want to explore alternatives; either to add features, or broaden retro-compatibility. The Photoshop extensibility layer grew over time - as follow a brief overview of what is, and historically has been, available.
Plug-ins (Photoshop SDK) This is something we’re all familiar with, so that the layman calls everything (panels included) plugins. Strictly speaking, you build a plug-in writing in some C-like language (C, C++, Objective-C), using Apple XCode or Microsoft Visual Studio compiling with the Photoshop SDK¹¹. There are several type of plug-ins, the most common of which: • Filter: pixel crunching machines. • Automation: accessing all Photoshop scriptable events. • Format, Import and Export: input and output for specific devices or additional file formats. In some cases, Plug-ins are actual stand-alone application whose interaction with Photoshop is limited to getting and injecting back image data. ¹¹http://www.adobe.com/devnet/photoshop/sdk.html
1
2
1. Photoshop Extensibility
Filter Forge Plugin
Unless you have a good knowledge on both the language and the related tools, plug-ins programming is possibly the steepest path on Photoshop enlightement.
Scripting With a script you programmatically drive Photoshop; most of what is not available in the DOM (Document Object Model - pretty much incomplete if compared to, say, InDesign), is within your reach using ActionManager code: not the brightest example of API usability, but a tremendous power at your disposal. You can script Photoshop using AppleScript on Mac, Visual Basic on Windows, or Extendscript on both platforms. In fact, there are three distinct layers of scripting available within Photoshop, as follows.
Extendscript Extendscript (a superset of Javascript¹²) is the foundation of scripting in a variety of other Creative Cloud applications (Bridge, Illustrator, InDesign, etc), and it’s what you’re going to use to impart ¹²ECMA-262, plus EX4 (ECMA357), plus Adobe’s non-standard stuff like Filesystem management, Reflection interface, operator overloading, etc.
3
1. Photoshop Extensibility
commands to the host app from within HTML Panels. Using the peculiar ScriptUI class, you can build Graphic User Interfaces as well, like:
xbytor’s Image Processor Pro
Scripting and scripted dialogs are retro-compatible back to CS3 and earlier, if you don’t mind distributing unobfuscated (plain) code.
TCP/IP (Connection SDK) Less known option, yet worth exploring: from CS5 onwards, you can establish a TCP connection with Photoshop and send/receive Extendscript messages and image data. But who is Photoshop messaging with? For instance, but not exclusively, a mobile application, built in Java for Google Android, Swift for iOS, or if you’re inclined even Adobe AIR.
1. Photoshop Extensibility
4
I would say that you can use the Connection SDK with a framework such as Ionic¹³ too, but I’m just speculating.
Generator First released with Photoshop CC (14.1), Generator has been primarily marketed¹⁴ as a technology that lets you export images in background, based on layer names. Actually, there’s much more: a Node.js server that communicates with Photoshop via Kevlar API (Extendscript), and exposes an Event based API for third-party plugins - mainly using Generator to access/extract resources from within Photoshop. Panels can talk to Generator too. From the very beginning, it has been open-sourced on GitHub¹⁵.
Flash Panels The first Photoshop Panel appeared back in CS4 and was based on a framework called PatchPanel, which never left Adobe Labs¹⁶ (the Labs are sort of an experimental technology preview: that might, or might not, find a way to actual Adobe products). According to conventional wisdom, one of the main promoters of customizable panels has been the former Photoshop Product Manager John Nack, now at Google. It was of course a Flash thing, because those were the Happy Flash Days at Adobe¹⁷. Flash Panels are supported from CS4¹⁸ up to CC (Photoshop v.16) included: they were built in Flex/ActionScript using Flex Builder (Adobe’s customization of Eclipse) as the IDE, with the help of a plugin called Adobe Extension Builder. Strange as it may sound, Extension Builder v2.1¹⁹ is still available as a subscription for about EUR 10 per month, as opposed as the v3.0²⁰ targeted to the newer HTML Panels, which is free. One of the main catches of Flash Panels, with hindsight, is that you were lured to write all of your Photoshop code directly in Actionscript - being the alternative to keep the Extendscript and just evaluate it, inelegantly going back and forth from the Panel to Photoshop²¹, and vice versa. Two problems: 1. Actionscript is strongly typed, Extendscript is not. If you’re used to typecasting (i.e. implicitly change the data type, say, from String to ArtLayer) you will spend an awful amount of time trying to fix loosely typed code that suddenly stops working. ¹³http://ionic.io ¹⁴http://blogs.adobe.com/photoshop/2013/09/introducing-adobe-generator-for-photoshop-cc.html ¹⁵https://github.com/adobe-photoshop/generator-core ¹⁶http://labs.adobe.com ¹⁷Tons of Flash history and nostalgia in this article. ¹⁸Photoshop CC2015.0.1 implements Node version 0.8.22 (log “process.version” to get it), CC2015.1.1 and CC2015.5 use the io.js branch v.1.2.0.
Generator relies on a Node.js different version (currently 4.3.1 - find the Generator’s node executable in Photoshop CC2015.5.app/Contents/MacOS/ and run ./node -v). ¹⁹http://www.adobe.com/it/products/adobe-extension-builder.html ²⁰http://labs.adobe.com/technologies/extensionbuilder3/ ²¹This is actually what we’ve ended up doing in HTML Panels.
1. Photoshop Extensibility
5
2. Developers who wrote and maintained Actionscript libraries for Photoshop have found themselves empty handed when the wind changed to HTML - facing the burden to re-rewrite their whole codebase back in Extendscript. In order to let Flash Panels spread to a bigger audience, Adobe released Configurator²², a visual, drag and drop utility to create Panels without coding experience. Even if it didn’t support the whole range of User Interface tools provided by Extension Builder, some remarkable extensions²³ have been built with it. Configurator, being an AIR app outputting Flash Panels, is now unmaintained²⁴; even if many users have requested an HTML port, it has never been announced.
HTML Panels Unless you’ve been living in a cave, you know what has happened to Flash²⁵. In four years or so a new breed of Panels has emerged - now HTML is the reigning standard. Since the whole book is devoted to the topic, I will spend little time writing about them in this Photoshop Extensibility overview. HTML Panels are supported from Photoshop CC, which is the only version that can handle both Flash and HTML at the same time, onwards. We’re possibly allowed to think that they will last longer, for it is a food that Photoshop itself eats: the Library Panel, the Export As dialog, the Welcome screen have been coded by Adobe as HTML Panels, for instance. Since web development appears to be the wave to ride, the time invested learning them is likely well spent.
An example of HTML Panel
HTML Panel development is free, as opposed to how it happened for Flash Panels. Extension Builder preview 3²⁶ is very likely unmaintained and won’t support the latest CC out of the box²⁷: you can build extensions using any text editor and linking the open sourced libraries.
²²http://labs.adobe.com/downloads/configurator.html ²³http://www.cs-extensions.com/products/cpt/ ²⁴My own personal bet is that it will stick to ES3 indefinitely, for a variety of reasons that don’t fit in this book. Check out extendscriptr, an
independent project that compile ES5 and ES6, also known as ES 2015, back to ES3 / ExtendScript compliant code. ²⁵http://www.commitstrip.com/en/2015/07/15/a-brief-history-of-flash/ ²⁶http://labs.adobe.com/technologies/extensionbuilder3/ ²⁷Latest version - which is still a Technology Preview - is dated Aug 1st, 2013. It can be tweaked to be used on Photoshop-latest, read the next chapter for detailed instruction.
2. The HTML Panel Stack
6
2. The HTML Panel Stack
7
Flash Panels used to be AIR²⁸ applications running within the Host App thanks to APE (Adobe Player Embedded); not surprisingly, HTML Panels are web applications running within the Host App, such as Photoshop. But what’s under the hood? How do we start building them?
CEP: Common Extensibility Platform Formerly known as Creative Suite Extensible Services (aka CSXS) and later renamed Common Extensibility Platform (aka CEP) is the whole suite of technologies embedded in Creative Cloud desktop applications that makes the subject of this book possible - CEP has become synonymous with HTML Extensions. Let’s imagine a Panel as a stack: the technologies are actually integrated, but visualizing them as layers might help.
CEF: Chromium Embedded Framework That’s the main container: Photoshop implements CEF²⁹ (not to be confused with CEP), an embedded Google Chrome browser³⁰. CEF provides the technology needed to run web apps, and includes its own Javascript rendering engine (the well known Google V8³¹, the very same Node.js is based upon).
HTML and CSS When you look at a panel, what you see is the rendered HTML, styled. Nothing different from what you’re used to - if elements on a page display correctly on Google Chrome, they’re supposed to work in a Panel too. According to Adobe, the following features are supported: • • • • • • • •
Video Audio Drag and Drop Canvas SVG Web Workers Web Storage Web SQL Database
²⁸https://en.wikipedia.org/wiki/Adobe_AIR ²⁹https://en.wikipedia.org/wiki/Chromium_Embedded_Framework ³⁰The version implemented in Photoshop CC2015.5 is CEF 3.2272.78, Chromium 41.0.2272.104. ³¹https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
2. The HTML Panel Stack
• • • • • • •
8
Application Cache Server sent events Form input types Form elements Form attributes File API Session and Persistent Cookies
A note about Cascading Style Sheets. Adobe doesn’t provide any official CSS to be used in third party panels: you’re free to implement the ones you like better, or borrow ideas used in Photoshop’s own HTML panels. I’ll cover styling in a dedicate section.
Javascript The ubiquitous JS is the foundation of Panel’s operations. You can plug in your framework of choice such as AngularJS, in order to implement the MVC (Model View Controller) pattern; or make Ajax calls, store data, send Database queries, interact with the server side, whatever you might need. As I’ve mentioned above, the JS pertaining to a Panel is interpreted by the Chromium’s V8 engine - that implements ECMAScript 5th version. Also, Photoshop features a built-in³² instance of Node.js³³, so you’re free to require() code in your JS, use core packages e.g. fs and http, grab available ones from NPM, or write your own modules.
Extendscript Finally, the code driving the Host App is Extendscript (aka JSX, like its default file extension). All the Photoshop heavy lifting - duplicate a document, apply a filter, etc - belongs to the JSX layer, which has its own distinct Virtual Machine (VM). I’d like to stress the above sentence: JS and JSX are interpreted and executed by two separate engines. Sadly enough, Extendscript is stuck to ECMAScript 3rd version³⁴ - that is to say: Photoshop will not understand what the following line means (and throw an exception): 1
["a", "b", "c"].indexOf("b"); // ReferenceError: indexOf is not a function ³²Photoshop CC2015.0.1 implements Node version 0.8.22 (log “process.version” to get it), CC2015.1.1 and CC2015.5 use the io.js branch v.1.2.0. Generator relies on a Node.js different version (currently 4.3.1 - find the Generator’s node executable in Photoshop CC2015.5.app/Contents/MacOS/ and run ./node -v). ³³http://nodejs.org ³⁴My own personal bet is that it will stick to ES3 indefinitely, for a variety of reasons that don’t fit in this book. Check out extendscriptr, an independent project that compile ES5 and ES6, also known as ES 2015, back to ES3 / ExtendScript compliant code.
2. The HTML Panel Stack
9
Layers communication So, if Javascript and Extendscript belong to different VMs, how is that the Panel magic can happen that is: what is that makes a Panel communicating with the Host Application (such as Photoshop)? On one side, JS can use PlugPlug (a shared Adobe technology component) to send a message to the JSX engine like “Dear Extendscript VM, can you evaluate this command for me?”, and the JSX layer is kind enough to perform the task and return back the result to the JS for further processing. On the other side, the JSX can emit Events - carrying a payload, so data can be transferred. Events which the JS can listen to, and react accordingly; I’ll be covering in depth these mechanism, so just don’t worry now. To sum up, an HTML Panel is a modern web application based on HTML5, CSS3, JS (ES5 and Node.js), which deals with the host application sending messages to, and listening for Events from, the host app’s JSX Virtual Machine. Yet, from the sheer point of view of Photoshop operations, nothing changes - there’s no new hook, everything’s based on good old scripting.
3. Setting up the environment Code editors A wise recommendation is: use what you’re already familiar and/or more productive with. You can code HTML Panels with just a plain text editor, but let’s inspect some of the possibilities.
Adobe Extension Builder 3 It’s a free Eclipse plugin that appears to be unmaintained³⁵ since mid-2013; yet it’s usable.
Adobe Extension Builder Preview 3
To date, it still is the closest thing to an Extension development IDE available (templates, code completion, debugging, etc), but you have to like Eclipse. In order to be able to use it, follow these steps. • Download the Juno³⁶ version (newer ones won’t work). • Download Extension Builder³⁷. ³⁵If I were you, I wouldn’t hold my breath waiting for a revamped version of Extension Builder 3. ³⁶https://www.eclipse.org/downloads/packages/eclipse-classic-422/junosr2 ³⁷http://labs.adobe.com/technologies/extensionbuilder3/
10
11
3. Setting up the environment
• Install Extension Builder from the Eclipse menu Help > Install New Software… You need to Add… a new Local… repository pointing to the downloaded Extension Builder, then confirm few times to have it finally installed. • Create a File > New > Other.. and pick Application Extension Project from the Adobe Extension Builder 3 folder. You can visit Eclipse Help > Adobe Extension Builder 3 Start Page to find the (quite good even if slightly out-of-date) documentation about it. Mind you, you need to manually modify some of the preferences in order to target newer versions of your Host App (Mac users: point to the exec within the App’s package):
Eclipse new Settings
Also, you need to manually update JS libraries code with newer ones (CSInterface.js, Vulcan.js, etc. - which I’ll cover later on).
Atom, Brackets, SublimeText GitHub’s (free) Atom³⁸ editor is a viable choice, yet for both the (free) Adobe Brackets³⁹ and (paid, but lovely⁴⁰) Sublime Text⁴¹ there are plugins made by David Deraedt⁴² which help scaffolding new CC Extension projects. ³⁸https://atom.io ³⁹http://brackets.io ⁴⁰Sublime Text future seems uncertain too, since its developer took the vow of silence and releases languish. ⁴¹http://sublimetext.com ⁴²https://github.com/davidderaedt?tab=repositories
12
3. Setting up the environment
Sublime Text + CC Extension Plugin
Brackets also provide some great Intellisense for your own JS files, which is definitely a plus.
Visual Studio Code When I’m writing this, there’s still room for improvement on the Intellisense side of this new, free Microsoft multiplatform editor (Mac, Win, Linux). I would keep an eye on it, it looks really promising.
Getting started: setting the Debug Flag On each of your development machine, you need to somehow tell Photoshop that you’re going to mess up a bit with Panels code, otherwise you’re going to run into a message complaining about a missing signature. In short, you need to set the Debug Flag. Confused? Read along. When Photoshop boots, it checks whether the installed Panels can be actually loaded and run; among the rest, it looks for signing/timestamping - an important topic that will deserve its own Chapter later in this book. The relevant bit of information that you need right now is: Photoshop doesn’t want you to modify the installed Panels’ code, it’s a mortal sin, and the Panel won’t load anymore. Since, during the development, modifying code (and/or cursing) is your prominent activity, you would rather prefer Photoshop not to be that picky about the Panel constantly changing its source.
3. Setting up the environment
13
Luckily, the so-called Debug Flag can switch off this behaviour and bypass the extension signature check. On a Mac, fire the Terminal and type: defaults write com.adobe.CSXS.7 PlayerDebugMode 1
Which is the same as finding the file ∼/Library/Preferences/com.adobe.CSXS.7.plist, opening it with XCode or any other .plist editor, and adding a new PlayerDebugMode Key of type String with value “1”. In order for the changes to apply, you might need to either restart OSX (quicker), or open Activity Monitor and kill all the running instances of cfprefsd - this will force a new .plist scan to update the cache. For Windows: run Regedit, browse to: HKEY\_CURRENT\_USER/Software/Adobe/CSXS.7
then add a new PlayerDebugMode key of type String with value “1”. Mind you: in case you want to test your panel on different versions of Photoshop, you need to add the debug flag to each and every one of the required CSXS files, which Photoshop matching versions are as follows: • • • •
com.adobe.CSXS.7 = CC2015.5 com.adobe.CSXS.6 = CC2015 com.adobe.CSXS.5 = CC2014 com.adobe.CSXS.4 = CC
Installation folders Now that you can momentarily forget about extension signatures, it’s time to know where HTML Panels belong in the User’s HD - their path. It’s a slightly more complicate matter than I would find appropriate, so I’ll keep it as short as possible for you. 1. Of course the path is different on OSX and Windows. 2. It depends on whether you want the Panels to be available for all the Users of the computer, or the currently logged User only. 3. It also depends on the Photoshop version you’re targeting (I won’t consider anything below CC). The path for Windows is: (User): C:\Users\\AppData\Roaming\Adobe\\extensions\
3. Setting up the environment
14
(System): C:\Program Files (x86)\Common Files\Adobe\\extensions\ While on Mac: (User): ∼/Library/Application Support/Adobe//extensions
(System): /Library/Application Support/Adobe//extensions Mind you, the first is the User’s Library, the second is the System’s Library⁴³. is CEPServiceManager4 for Photoshop CC, CEP for any next version so far (CC2014, CC2015, CC2015.5, etc). In case the /extensions folder doesn’t exist, feel free to create it.
It’s still debatable whether you should deploy extensions at the User’s or System’s level - I prefer the former, which possibly leads to fewer permission issues.
Download the Libraries Go to the CEP7⁴⁴ GitHub repository (or whatever CEP major version is the one that you’re interested into), and grab the following files: • CSInterface.js • Vulcan.js • AgoraLib.js Keep them handy because you’ll need to link them in your extensions.
Storing projects Over the years I’ve tested few different setups, and now I’ve settled to the following one. As a single developer, I use Git⁴⁵ as a Version Control System, pushing to BitBucket⁴⁶: which allows unlimited and free private repositories (also their SourceTree⁴⁷ Git client is my favorite). Each project has of course his own directory/repository, which belongs to a Dropbox local folder as a safety net. Mind you: some Cloud aggregators⁴⁸, such as the otherwise great odrive⁴⁹, won’t backup Git repos. Then, I create a Symbolic Link⁵⁰ from each of my Dropbox development folders, to the Installation Folder. On Mac (open Terminal), it’s like: ⁴³You don’t need to deploy on both folders, either the User or the System ⁴⁴https://github.com/Adobe-CEP/CEP-Resources/tree/master/CEP_7.x ⁴⁵https://git-scm.com ⁴⁶http://bitbucket.org ⁴⁷https://www.sourcetreeapp.com ⁴⁸Aggregators are services which allow you to manage multiple Cloud accounts at once, such as Dropbox, Google Drive, Box, OneDrive, etc. ⁴⁹http://odrive.com ⁵⁰Which is different than creating an alias: symlinks work, aliases don’t.
3. Setting up the environment
15
ln -s /Users//Dropbox/Projects/ALCE /Users//Library/Application\ Suppo\ rt/Adobe/CEP/extensions/ALCE
This way I can keep coding on my backup-ed, Git managed, local Dropbox folder without the need to move stuff around to deploy and test on Photoshop. Windows users: I’ll be using Linux/Mac-style commands on the commandline throughout the book. I suggest you to install Cygwin⁵¹ so that you can run commands just as they’re written here.
⁵¹https://www.cygwin.com
4. Building up “Hello World!” Greeting the world is (by law) the first step in every language, and who am I to break traditions. In fact we’ll be coding not one but three such panels, and each exercise is nothing but a pretext to tell you about some very important extension feature. So get ready and don’t just skip to the next chapter, I can read your mind.
Take 1: Manifest.xml Create a Hello World folder in the appropriate /CEP/extensions path to contain the whole project, then create a new index.html file with the following content: 1 2 3 4 5 6 7 8
Hello World! Hello World!
No really, do it. I’m afraid if you reboot Photoshop and look in the Window > Extensions menu, you won’t see it there. Photoshop needs quite a lot of extra information about your extension, such as its unique ID, the panel size, the version of the Host App it supports, etc. All this (and much more) goes into a manifest.xml file that mandatorily has: 1. To exist. 2. To belong to a CSXS folder in the project’s root. If it’s missing, or mistyped (which is not unfrequent), the panel won’t load. So, the simplest extension’s tree ever is:
16
4. Building up “Hello World!”
17
. ├── CSXS │ └── manifest.xml └── index.html
You can look at existing extensions’ manifest to check what the available tags are, but as follows is a pretty standard one for our super minimal Hello World: Example of a manifest.xml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
./index.html
4. Building up “Hello World!”
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
./jsx/photoshop.jsx true Panel Hello World! 150 300 100 150 200 350 ./icons/iconNormal.png ./icons/iconRollover.png ./icons/iconDisabled.png ./icons/iconDarkNormal.png ./icons/iconDarkRollover.png
Salient elements:
18
4. Building up “Hello World!”
19
• Version: this is tricky, because it refers to the version of the Common Extensibility Platform (CEP - covered in following chapters), and must correspond to the value set in the RequiredRuntime CSXS Version. For CC it’s "4.0", CC2014 is "5.0", CC2015 is "6.0", CC2015.5 is "7.0". • ExtensionBundleId: an extension can bundle multiple Panels, and this is the unique ID for the Bundle - required even if yours is a one-panel-only Bundle. • ExtensionBundleVersion: the current version of your Bundle. • Extension Id: the unique ID for the extension (best practice is to add a .panel or .panel1 to the ExtensionBundleId), and the Version there is finally your extension version. • HostList: contains the Host tag, which has the – Name: see the Debugging section for a list of 4chars codes of all the applications supported. Mind you, for Photoshop you need to explicitely use both "PHSP" and "PHXS"⁵². – Version: the supported version of the host app. Either an Array such as "[16.0,16.9]" (from 16.0 to 16.9), where square brackets mean “included” and round parens mean “excluded”; or a straight number like "15.0", which means from 15.0 onwards with no upper limit. Please don’t do "[16.0,9999.9]" as I’ve seen. • MainPath: the HTML entry point of the Panel. • ScriptPath: the JSX entry point of the Panel (covered below). • Geometry: sets the default (required), max and min (optional) size of the panel.
CEP7 updates Starting with Photoshop CC2015.5 you’re allowed to move the node inside , that is: specify a custom Host app on a per extension basis, like: 1 2 3 4 5 6 7 8 9 10 11 12 13
⁵²They refer to Photoshop and Photoshop Extended, a relic from the past when they were marketed as different products. See here the reason why you need them both in the manifest.xml.
4. Building up “Hello World!”
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
20
This is because your Extension can bundle multiple Panels (you’ll see this later on): this way you can customize a Panel for, say, ID, one for PS, etc. To let you taste the salty sea of HTML Panels just grab the manifest.xml I’ve provided, save and reboot Photoshop. Now find the “Hello World” panel in the Window > Extensions menu.
Problems running the Extension? Try downloading the provided source code and compare it with yours. Is something missing? Chances are that there’s some error in the manifest.xml, like a curvy quotation marks (“ ”) instead of dumb ones (" "), or mismatching CSXS Version. To validate the manifest, download the ExtensionManifest_v_7_0.xsd⁵³ file⁵⁴ and upload it alongside with your own manifest to this Schema Validation⁵⁵ service.
Take 2: ExtendScript An important and still missing piece of the puzzle is the interaction with the Host App - Hello World must somehow get in touch with Photoshop. As you remember from the manifest.xml, the ⁵³https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_7.x/ExtensionManifest_v_7_0.xsd ⁵⁴Or the version of the CEP you’re targeting: there are .xsd files for CEP7, CEP6 and CEP5. ⁵⁵http://www.corefiling.com/opensource/schemaValidate.html
4. Building up “Hello World!”
21
JSX entry point (referred to the extension root) is set there as shown in this excerpt: ./index.html ./jsx/photoshop.jsx
The above means: as soon as the Panel needs it⁵⁶, the content of the ./jsx/main.jsx file is going to be read and evaluated in the JSX engine. If it contains statements, they’re going to be executed; if it contains function declarations, they will stick into the JSX Virtual Machine, ready to be called later if/when needed, you’ll see in a minute how. Let’s group files more systematically - adding to the panel a js, jsx and css folder, the tree becomes: . ├── │ ├── │ ├── ├── │ │ │ └──
CSXS └── manifest.xml css └── styles.css index.html js ├── libs │ └── CSInterface.js └── main.js jsx └── photoshop.jsx
The improved index.html now contains a button (small steps I know): index.html
1 2 3 4 5 6 7 8 9
Hello World! ⁵⁶The JSX isn’t really evalued at Panel loading, but only when the first .evalScript() call is fired.
22
4. Building up “Hello World!”
10 11 12 13 14 15
Say Hello
and the JSX has code for popping up an alert: photoshop.jsx
1 2 3
function sayHello(){ alert("Hello from ExtendScript"); }
As you might foresee, a button click will trigger the Photoshop alert - that is: we will bridge the gap from the panel to the host app. Please notice that there’s a ./js/libs folder containing the CSInterface.js file, that in the previous chapter I’ve recommended you to download from the CEP GitHub page. For the time being, think about CSInterface as the JS bridge between you and CEP features implemented in Photoshop; the next Chapter is going to give you an extensive coverage of what is CSInterface all about. Our main.js file contains:
Hello World take 2
main.js
1 2 3 4 5 6 7 8 9 10
(function () { 'use strict'; var csInterface = new CSInterface(); document.getElementById('btn_test').addEventListener('click', function () { csInterface.evalScript('sayHello()'); }); }());
Let’s have a deeper look at it.
23
4. Building up “Hello World!”
1. Everything is wrapped with an Immediately-Invoked Function Expression (aka IIFE): it creates a block scope and avoids polluting the global environment.⁵⁷ 2. The CSInterface class is instantiated and stored in a variable. 3. A listener for the click event is attached to the button with id="btn_test" (the only button our poor html has). 4. In the callback, the csInterface.evalScript method is used to send to the Photoshop JSX engine the 'sayHello()' string for evaluation.
Hello World take 2 in action
As a result, when you press the Panel’s Say Hello button, its click event listener fires the callback, which in turn says: “Hey Photoshop, does 'sayHello()' mean something for you?”. Photoshop in turn looks whether the manifest.xml knows about any JSX file to parse (“here it is Sir, it’s photoshop.jsx”) and hands it to its JSX engine. Finally sayHello() is run, and the alert pops up.
JSX silent failures An annoying trait of the ExtendScript implementation in HTML Panels is that if your JSX code contains errors such as typos, it will fail silently: that is, you have no clue about the reason why it doesn’t behave as you think it should. As an example, sabotage the sayHello function mistyping alerr instead of alert. If you run this in ESTK⁵⁸ you will get ReferenceError: alerr is not a function as soon as you try calling sayHello. This is not the case when the above happens in the context of an HTML Panel, so be aware. Mind you, wrapping the whole JSX content with a try/catch block won’t work. Also, if the photoshop.jsx file is totally empty (that is, no chars), any evalScript() call that you might do not referencing existing functions (e.g. csInterface.evalScript("alert('Hello!')") will fail. Put at least some chars in there, a comment, whatever. ⁵⁷Does that sound like Sanskrit to you? Read this clear article to understand more about it. ⁵⁸ExtendScript Toolkit.
4. Building up “Hello World!”
24
We’ll make extensive use of both CSInterface methods and ExtendScript code in the next chapters, so if this Hello World take 2 exercise has left you with unanswered questions (is there a way to transfer a payload between JS and JSX? Is the other way around possible?), be aware that we’ll touch those topics again and again, and you won’t miss code examples.
Take 3: Debugging The Hello World third iteration is about debugging, an activity we all love. How do you do it? Remotely is the answer - i.e. the panel will act as a server and you’ll be connecting to it. In the root folder of your extension, create a blank file called .debug, which makes it hidden⁵⁹.
You can use your Text Editor for this task, or the Terminal (find it in the Applications/Utilities folder). First, cd in the appropriate location (you can see in the above screenshot that Folders with spaces in the name are escaped with a \ which is the default when you drag and drop a Folder from Finder in the Terminal window), then touch the .debug file to create it. This file needs to be formatted as an XML and should contain information about the ID of your extension (i.e. it must match the ID specified in the manifest.xml), and the host/port (in the range 1024 – 65534) you want to connect through. Example of a .debug file
1 2 3 4 5 6 7 8 9 10 11 12 13 14
⁵⁹On OSX, a filename that starts with a dot is hidden.
25
4. Building up “Hello World!”
15 16 17 18 19 20 21 22 23 24 25 26
/> /> /> />
Now, while your Photoshop extension is open, point the Chrome browser to http://localhost:8088 (of course use the port you’ve set in the .debug file). You should see something like this:
Localhost:8080
When you click the Hello World link (which is the title tag set in the index.html) the Chrome Developer Tools will open and you’ll be able to inspect/debug your extension, set breakpoints, log messages, like any other web application. Introductory tutorials can be found on DevTools page⁶⁰, Code School⁶¹, TutsPlus⁶². Breakpoints can be set in the Sources tab, refreshing then the view with Command or Control + R in order to restart the panel. Mind you, the Chrome Developer Tools cannot reach the JSX level – it’s just for the HTML panel and its JS; if you’re wondering, a debugger call in the JSX doesn’t fire up ESTK. If you want to log from JSX in the Chrome Console, you need to use Custom JSX Events - see Chapter 7. ⁶⁰https://developer.chrome.com/devtools ⁶¹https://www.codeschool.com/courses/discover-devtools ⁶²http://code.tutsplus.com/courses/chrome-developer-tools
26
4. Building up “Hello World!”
Chrome Developer Tools
Let me list few handy debugging caveats.
Kill the Cache You will save hours of frustration installing a Google Chrome extension called Cache Killer⁶³: as the name suggests, it prevents Chrome Developer Tools from loading a cached version of your panel, driving you crazy. A typical scenario is you fixing code, relaunching the extension, still getting problems - until you find out that Chrome didn’t retrieve the latest corrections and still shows you the old panel. Thanks to the InDesign developer Gabe Harbs⁶⁴ who pointed me to it.
Console scrolling tip If you can’t scroll the Chrome Developer Tools Console (that is, when it’s full you can’t see any more logged lines) the workaround is found here⁶⁵ – basically you need to inject this CSS to make it work again: html /deep/ * { min-width: 0; min-height: 0; }
Using cefclient In the Adobe-CEP GitHub repository you can download cefclient⁶⁶, either Mac or Windows. It’s, well, a CEF client that you can use instead of Google Chrome: be aware that (at least on Mac), you need to pass a custom flag to the executable or it won’t connect with Photoshop. So the actual Terminal command is: ⁶³https://chrome.google.com/webstore/detail/cache-killer/jpfbieopdmepaolggioebjmedmclkbap?hl=en ⁶⁴http://in-tools.com/ ⁶⁵https://github.com/Adobe-CEP/CEP-Resources/issues/35#issuecomment-165759781 ⁶⁶https://github.com/Adobe-CEP/CEP-Resources/tree/master/CEP_7.x
4. Building up “Hello World!”
27
cd ./cefclient.app/Contents/MacOS/cefclient --off-screen-rendering-enabled
Hello World wrap-up Hopefully this chapter has raised more curiosities than the information it has given - JSX evaluation, CSInterface, debugging and also the manifest subtleties will deserve extra mentions in the following pages; I’d say that for a Hello World there’s already too much on the table, see you in the next chapter.
Enjoyed the content so far? I’m afraid here ends the free content that I’ve been happy to share with you! Much more advanced topics, the fully commented code of 28 custom made panels covered in the book, and three hours of HD video tutorials await you for purchase on h#p://htmlpanelsbook.com You can subscribe to the newsle#er to get a preview of the video content as well (half of an hour, for free) - no spam involved. Feel free to get in touch if you want - in the Course homepage you can find email, socials, etc. !ank you and kind regards from Italy! Davide Barranca
The Full Package is available HERE!
Acknowledgements The idea of writing this book didn’t strike me until I read ProgWriter³¹⁹ by Azat Mardan, so he’s definitely the one I should thank first. Without his input I would have sticked to few, scattered blogposts, instead of embarking on this long journey: which, frankly, has made me learning more that I initially would have supposed. I owe a lot to many people from Adobe: over time I’ve proved to be a pest with my questions, feature requests and bug submissions - despite that, they’ve always been supportive and listening to my thoughts. Engineers who actually build the products we’re using, care as much as we do about them - when I’ve moved criticisms (and I did) it wasn’t toward them: they’re not the ones who decide whether to invest time and resources on a particular project. Each and every one of them has been of great help: I’d like to thank Tom Ruark, Jeffrey Tranberry and Eric Ching; Arthur Guo Wei, Hui Ding and Lea Savage; Hallgrimur Bjornsson and Jonathan Ferman; Krystal Woods and Fraser Gregor. Thank you all. The developers’ community of HTML Panels isn’t huge (yet!); I’ve exchanged thoughts and received a great deal of help and friendly support from many people involved in the challenging business of building and marketing extensions, and/or in the Scripting community. I’d like to mention and thank for their precious time Chris Russ, Cameron McEfee, Matias Kiviniemi, Sandra Voelker, Anastasiy Safari, Olav Kvern, Gabe Harbs, Marc Autret, Loic Aigon, Peter Kahrel, Kris Coppieters, Norm Sheeran, Greg Benz, Franz Hoffman, Joel Galleran, James Stewart, Max Penson, Chuck Uebele, Michel Mariani, Marek Hrabe, Sergey Kritskiy, Kamil Khadeyev, Anton Lyubushkin, Trevor Morris, Christoph Pfaffenbichler. A special thank to xbytor from the PS Scripting community. Giuliana Abbiati (aka Cromaline), has been my Panels’ alter ego: without her support, sincere friendship and truckloads of chocolate I wouldn’t have accomplished the half of this. Thank you. Last but not least, I owe to my wife Elena not only all the time this book has stolen to our marriage in the last 7 months, but much more, for she took care of everything I’ve neglected - without her love and support none of what I’ve done in the last 16 years would have been possible. Included our daughter Anita, who - I hope - will remember dad constantly grumbling and cursing at some broken code as a lesson on persistence. Thank you too, reader - and please: get involved, participate, be vocal (also with Adobe!) Let’s make the HTML Panels community stronger and wider, which is the only way to keep this business profitable, long lasting and fun. ³¹⁹http://progwriter.com/
268
Copyright © 2016 Davide Barranca Adobe® Photoshop® and Adobe® Creative Cloud® are registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners. THIS PRODUCT IS NOT ENDORSED OR SPONSORED BY ADOBE SYSTEMS INCORPORATED, PUBLISHER OF ADOBE PHOTOSHOP AND THE ADOBE CREATIVE CLOUD.
This book was made using Leanpub. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. I’d like to thank their team for the support, professionality and care - I couldn’t recommend them more if you’re interested in producing your own book.
269
