Scripting Photoshop, Part 1 — An Introduction

Whether it's automating tedious tasks, customizing commands, or adding new features, scripting makes almost anything possible in Adobe Photoshop.

Photoshop script (JSX)

The ability to script Photoshop debuted back in version seven as an optional plugin that could be downloaded from Adobe's website . As of version eight (CS), the scripting plugin is installed by default. Now, in version ten (CS3), scripting the backend of Photoshop is more accessible and powerful than it's ever been. Yet despite how long scripting has been part of Photoshop, it's surprising how few people take advantage of it — and even more surprising, is the number of people who aren't even aware that Photoshop can be scripted.

The Scripting Advantage

So, what's so great about scripting, and what can scripts do that can't be accomplished by traditional actions? Well, while actions (including batches and droplets) are tremendously powerful and flexible, they have many limitations that scripts do not.

Consider, for example, something as simple as toggling the visibility of the current layer (i.e., turning a layer off if it's on, and vice versa). You could easily record an action to turn the layer on, or off, but you can't create an action that toggles the visibility. The problem is that actions aren't capable of decision-making, or "conditional logic".

Actions are also limited to executing commands within the hosted application, whereas scripts can communicate and exchange information with any (or all) of the applications in the Creative Suite. For example, you could write a script that initiates a procedure in Adobe Illustrator CS3 and then forwards the results to Adobe Photoshop CS3 for completion. Now that's pretty cool!

Some Creative Suite applications even allow you to use scripts to customize the user interface, and create custom commands and panels.

Installing Scripts

Installing scripts is much the same as installing any other preset. First, copy the script into the Presets/Scripts subfolder:

Mac: <hard drive>/Applications/Adobe Photoshop CS2/Presets/Scripts/
PC: C:\Program Files\Adobe\Adobe Photoshop CS2\Presets\Scripts\

Then, after you quit and restart Photoshop, the newly installed scripts will automatically appear in the File » Scripts submenu (in alphabetical order).

Note that you can also create subfolders inside of the Presets/Scripts folder. This is helpful if you have a lot of scripts, or if you want to keep your own scripts separate from those you acquire from a third party.

To run a script, simply select it by name from the File » Scripts submenu, or choose File » Scripts » Browse to locate and run scripts that don't appear in the Scripts menu.

Tip: Scripts and/or folders of scripts may be disabled (i.e., hidden from Photoshop) by prefixing their names with a tilde (e.g., "~Disabled-Script.jsx").

Scripts Within Actions

Adding a script to an action is the same as adding any other command to an action: simply select the script (from the File » Scripts menu) while in record mode and the script will be inserted as a step in the action.

Alternatively, you can add a script to an action (whether in record mode or not) by using the Action panel's Insert Menu Item command:

  1. Select the action step that appears above where you want the script to be inserted.
  2. Choose Insert Menu Item from the Actions panel menu (Panel menu).
  3. When the Insert Menu Item dialog appears, choose File » Scripts » Script Name from the application menus.
    Insert Menu Item
  4. After pressing the OK button, the selected script is added to the action (below the previously selected step).

Now when you play the action, the inserted script will be executed as part of the command sequence.

Note: Scripts within actions are referenced by their absolute path (i.e., the complete path to the script on the local computer). This means that if you wish to share your actions with other people, they must install the script in the same location on their machine in order for the action to work correctly. Alternatively, they could just re-record or re-insert the script into the action.

Event-Based Scripts

Scripts (and actions) may also be executed automatically, based on an event, such as on startup, opening a document, or creating a new document. These kinds of scripts are called "event-based scripts".

To define an event-based script, choose File » Scripts » Script Events Manager. Once the Script Events Manager dialog appears:

  1. Turn on the Enable Events To Run Scripts/Actions checkbox.
  2. Choose an event from the Photoshop Event drop-down.
  3. Click on the Script radio button.
  4. Select the desired script from the Script drop-down (or choose Browse from the bottom of the drop-down).
  5. Press the Add button to add the event to the Event List.
  6. Finally, press the Done button to apply all changes and enable the event.
Script Events Manager

To remove an event, select it by name in the Event List and press the Remove button — or use the Remove All button to remove all events from the Event List.

To disable all events without removing them, simply turn off Enable Events To Run Scripts/Actions. Again, you need to press the Done button to apply all changes.

Tip: Did you know that the Script Events Manager (File » Scripts » Script Events Manager) is itself a script? That's right! The dialog you use to manage event-based scripts (and actions) is in fact written in JavaScript. The Image Processor (File » Scripts » Image Processor) is another example of a command in Photoshop that's entirely written in JavaScript.

Both of these scripts are located in the root of the Presets/Scripts folder, and serve as great examples of what can be accomplished with scripting. Just be careful not to modify the original scripts — at least not without first making a backup.

The ExtendScript Toolkit

Regardless of whether you install a single CS3 application or the entire Creative Suite, two other applications are installed by default: Adobe Bridge  and the ExtendScript Toolkit.

Adobe Bridge is a flexible and powerful viewer/organizer and serves as a hub for all Creative Suite applications. Note that Bridge can also be used to select files and initiate suite-wide script-based commands. Several scripts are available by default in Bridge's Tools menu, depending on which of the Creative Suite applications you have installed (e.g., Tools » Photoshop » Image Processor).

The ExtendScript Toolkit serves as a full-featured development and testing environment for ExtendScript in all CS3 applications. The Toolkit includes such features as syntax-highlighting, multiple undo/redo, Unicode support, and much more.

ExtendScript is Adobe's extended implementation of JavaScript, which offers all of the standard JavaScript features, in additional to:

For a complete overview of ExtendScript and the ExtendScript Toolkit, see Chapter 9 of the JavaScript Reference Guide.

Tip: The latest version of ExtendScript Toolkit is available as a free download from the Adobe Bridge Developer Center .

Reference Documents

For a more comprehensive understanding of scripting, or to learn how to create your own scripts, check out the many invaluable resources installed by default in the following location:

Mac: <hard drive>/Applications/Adobe Photoshop CS2/Scripting Guide/
PC: C:\Program Files\Adobe\Adobe Photoshop CS2\Scripting Guide\

Adobe Photoshop CS3: Javascript Scripting Reference Tip: The Scripting and Reference Guides are also available in electronic format (PDF) from Adobe's Photoshop Developer Center .

You can even purchase a printed book of the Photoshop Scripting Guide from Amazon.com  (although it's currently only available for Photoshop CS2).

Additional Resources

Below are several online resources dedicated to sharing scripts and information about scripting:

The Definitive Guide to JavaScript

JavaScript: The Definitive Guide There are a lot of great JavaScript resources and books out there, but JavaScript: The Definitive Guide , written by David Flanagan, and published by O'Reilly , is the must-have reference for anyone who's serious above JavaScript.

Now in its fifth edition, JavaScript: The Definitive Guide has been completely revised and expanded to cover JavaScript as it's used for today's "Web 2.0" applications. This book also documents every class, object, constructor, method, function, property, and constant defined by JavaScript 1.5 and ECMAScript version 3.

A must-have reference for expert JavaScript programmers... well-organized and detailed.”
— Brendan Eich, creator of JavaScript

For more information about JavaScript: The Definitive Guide, visit O'Reilly's website . You can also download a sample Chapter in PDF format from the following location: Chapter 21: JavaScript and XML .

A Practical Example

To learn more about scripting Photoshop, and to see a practical step-by-step example, be sure to read part 2 of this tutorial: Scripting Photoshop, Part 2 — A Practical Example.

 

If you enjoyed this tutorial, please consider supporting this site. As always, I welcome your feedback and suggestions. Also, if you have a scripting project that you'd like to discuss with me, please contact me with the details and I'd be happy to provide you with a free estimate.