“Professional Photoshop UXP – Script and Plugin Development with the new Photoshop API”, by Davide Barranca, Nov. 2023 (v1.0.0), 325 pages, eBook and code samples from €170.

Welcome to the (new) Jungle

Three years ago, Davide Barranca became more widely known to developers through his master class Professional Photoshop Scripting, the precursor to the present work. However, seasoned readers may recall his foray into the front lines in 2016 with the 300-page ebook HTML Panels Development. This automation jack-of-all-trades, recently enlisted by Adobe to contribute to the UXP API for Photoshop, brings a wealth of experience to the table. In his latest offering, Davide not only navigates the twists and turns of Adobe's extensibility history but also excels at conveying technical details in a narrative and educational framework.

The history of Adobe Scripting illustrated by Davide (fig. 1.7 of the book.) All is said!

This teaching talent is fully expressed in his great YouTube UXP series (which I often mention as a model), and this is the central quality of all his writings. Many technical books look like a pile of plates taken as is from the official documentation and re-arranged on the sideboard without the slightest invention. Professional Photoshop UXP connects all elements, providing a holistic view akin to interactive characters converging in your mind.

Aerial photo of a UXP plugin code offered in the book (listing 4.6).

Painfully stammering my first lines of UXP code, I need a ruler that tells me how to link the dotted lines from my (obsolescent) background. “UXP is a term that people attribute slightly different meanings to, depending on the context, Davide writes. At its core, it refers to a new environment created by Adobe, designed to facilitate the development of plugins and scripts (…). Within the UXP environment, specific components are shared among all applications. These components form the UXP API (Application Programming Interface), consisting of guidelines and resources such as UI components, file system access, network communication capabilities, metadata tools, and event handling mechanisms (…)”

Main Bricks and Tools

The book first covers the development environment and the fundamentals of UXP (DOM vs. API). The DOM layer is not new, conceptually, to an Id developer, because InDesign had from the outset the most comprehensive scripting infrastructure of any Adobe app. The case of Photoshop is particularly interesting in this regard. At its core, Ps is a “vast and sometimes enigmatic collection of commands accessible through its interface,” a kind of pure event system on top of which the DOM abstraction is built, “surfaced to Scripting as ActionManager (in ExtendScript) and now ActionJSON (in UXP).”

Partial view of an UXP script that reshapes the selection as a star.

Switching to modern JavaScript, “the Photoshop team responsible for Scripting saw an opportunity to revamp the DOM's structure and features completely. As a result, working with the Photoshop UXP DOM (…) entails adapting to a different structure, as the DOM has been expanded and rationalised…”

The tour de force of Davide's book is to introduce you to this toolbox (with many clear and practical examples) while revealing the subtleties of the UXP syntax in general — as you will use it with respect to any other Creative Cloud target. We can therefore read a large part of this guide as if Ps were only a case study:

• “UXP's primary strength comes from the single modern JavaScript engine that drives UI logic and scripting capabilities.” Regarding the scripts/plugins interface, “UXP takes a more restrained approach (than CEP), prioritising performance over a Standard feature set.” UXP's UI is not as rich as CEP's, “but it boasts a curated selection of Spectrum components, Adobe's very own design system.”

• UXP scripts are single-file entities (with a psjs extension) that you can think of “as supercharged Actions” in modal execution state. UXP plugins offer a much more extensive framework (they can include any number of panels and commands) and a “superior debugging experience compared to psjs.” Thus the author recommends the “creation of a dummy plugin that hosts your code and connects its execution to, say, a button click”.

The UXP Developer Tool debugger.

• JavaScript (and therefore UXP) now favors asynchronous programming with Promises, “simplifying the handling of non-blocking tasks that call for the host application's complete attention”. If you're coming from ExtendScript (synchronous approach) the paradigm shift will probably not be as intuitive as Davide presents it. Old reflexes will lead you to compensate by incorporating “massive amounts of async/await throughout (your) code”, but I suppose it is a necessary evil in order to gradually tame the asynchronous beast.

Note. - Since most methods are now asynchronous, they won't postpone the execution of the rest of your code. This allows you to think of tasks as in a non-modal frame (a bit like you do in event-driven programming). But Promises introduce specific difficulties that make them a tricky business, notably in matters of error handling. The purpose of the await keyword is to switch back to a synchronous behavior.

• While in ExtendScript most root entities (app, $, ScriptUI) were readily available in the [[global]] scope, in UXP you have to “explicitly import the modules you intend to use via the CommonJS syntax, and the require() method.” You will be grateful to Chapter 3 for finally giving you an intelligible explanation of all these syntactic spices, including ‘destructuring’ patterns like

    const { core } = require("photoshop");

Professional Photoshop UXP also provides you with all the equipment and links you need to get started: code editors, syntax highlighting, VSCode extensions, UXP Developer Tool (UDT), and a very detailed section on Jaroslav Bereza's Alchemist plugin that generates Action JSON code (see below).

Chapters 8 to 10 are also of public interest since they address:

   — The File system (fs module and UXP's FileSystemProvider, urls, storage…)

   — The basics of UI design (not as in-depth as Adobe UXP plugins development with React JS, by the same author, but still a great introduction), covering Spectrum UXP widgets and Web components.

   — XMP Metadata (schemas and namespaces, reading and editing metadata, etc), probably the best summary ever written on this topic since Photoshop (2024) has integrated the XMP utility module.

Davide's book is richly illustrated with diagrams and figures which allow you to immediately visualize the essential facts.

A New Era in Extending Photoshop

By roughly summarizing a few founding principles of UXP, I have barely touched on the main dish of the book. Although I'm anything but an Ps expert, I was immediately taken into this epic journey.

“Everything began in 1996: the Mad Cow Disease outbreak, the Spice Girls' debut album, and Photoshop 4 first implementation of Actions — a fundamental building block for automated workflows, allowing users to record, save and replay bits of Photoshop activity”. This is how Davide starts his chapter on Action JSON (the UXP equivalent of Action Descriptors). With “Climbing the DOM” (Chap. 4), this part gives you a full gauge of the possibilities opened up by UXP in automating the app.

A first remarkable aspect is the effort of abstraction finally carried out by Adobe regarding DOM objects (documents, layers, selections, colors, texts, fonts…). ‘Plural entities’ (well-known to Id developers as Collections) are now implemented as Proxy objects, several classes have an official, extensible prototype so you can “inject new methods and properties that each instance will inherit”, and the whole system is much better at capturing deeper functionalities like Type menu items. As an example, Davide builds a “Lorem Ipsum” plugin step by step.

Regarding Action JSON, the author answers a huge set of questions addressing the Action Manager legacy, how this low-level event system evolved over (so many) years and why a new JSON-like syntax (also referred to as BatchPlay) emerged. He then provides a dense overview of DOM polyfill, references, getters/setters, “multi-getters”, chained descriptors…

Partial view of Fig. 6.1, explaining the Chunky vs. Planar encoding of the imageData property.

Chapter 6 (“The Imaging API”) opens the doors to pixels and image data in Photoshop documents. As a “first really true UXP innovation,” this topic is fascinating and Davide's treatment of it goes well beyond the official reference. Even if you are remotely interested in image processing, you will be amazed by the algorithms and examples detailed here.

Considering that “it wasn't possible to programmatically get and set individual pixels in ExtendScript”, the Imaging API is a Pandora's box for developers and advanced users. The author devotes more than fifty pages to this subject, entering into the meanders of image data routines, getters and setters, chroma masks, steganography (!) and even Machine Learning integration — e.g. object detection using TensorFlow and its high-level interface ml5.js.

Partial view of Fig. 6.2, Getting pixels of a layer through the Imaging API.

Sated? Well, take a breath, because the next chapter discusses the alternatives dealt with in compiled languages: WebAssembly (WASM) and Hybrid Plugins implemented with C++. “Around late 2022, for the brave ones among us, Adobe introduced UXP Hybrid plugins in Photoshop. In short, Hybrid refers to integrating compiled C++ code within UXP plugins. Similar to the concept of ExternalObject in ExtendScript, they allow you to load dynamically linked shared objects written in C++ and use them in the UXP context.”

Here we enter the realm of black magic so read in full the section on debugging a Hybrid plugin in XCode! As a reward for your efforts, you will understand the inner workings of the Block Decomposition plugin generously documented by the author.

The fantastic Block Decomposition Hybrid C++ plugin.

Bottom Line

Professional Photoshop UXP is a consistent, prodigiously documented guide, aimed at both Photoshop experts and script/plugin developers wishing to expand their understanding of the UXP wave.

Davide Barranca is probably the only person who could gather this amount of information with such hindsight. The book is dense but always in touch with concrete needs. You will often have the feeling that it anticipates the questions you were going to ask yourself, which is the hallmark of true reference works.

• Main links (Davide Barranca works):
→ Professional Photoshop UXP (aka 2nd Edition of “Professional Ps Scripting”)
→ Adobe UXP Plugins development with React JS
→ UXP Series — Things You Need to Know (YouTube)
→ Professional Photoshop Scripting (legacy course)
→ HTML Panels Development (CC 2019)
→ Davide Barranca — Photoshop, etc

• Related links:
→ Photoshop API (2022)
→ Adobe UXP Developer Tool
→ Adobe Spectrum Design System
→ Visual Studio Code
→ Jaroslav Bereza
→ Alchemist for Photoshop
→ Node API
→ TensorFlow
→ ml5.js

• See also:
→ “HTML Panels Development” review (2016)
→ Getting Started with IDJS (InDesign UXP Scripting Format)
→ Other book reviews