Introduction to Scripting in Photoshop
Note: Programmers will often interchange the terms "function," "method," "Routine," "procedure," or "subprogram" for
the same thing. For the sake of simplicity and consistency, we'll use the term "method" to describe commands/tasks that
are built into the Photoshop DOM and we'll use the term "function" to describe custom commands/tasks that are outside
of the Photoshop DOM.
Launching the Extend Script Toolkit 2.
The ExtendScript Toolkit is the text editor you will use to write ExtendScript for these lessons. The ESTK helps make
writing scripts easier through syntax-highlighting, auto-complete, and built in debugging. The ESTK is installed when you
install Photoshop or the Creative Suite:
Mac: <hard drive>/Applications/Utilities/Adobe Utilities/ExtendScript Toolkit 2/
Windows: C:\Program Files\Adobe\Adobe Utilities\ExtendScript Toolkit 2\
Writing your first script.
I rarely start writing a script from scratch. I'll usually start with a template or existing script and modify it to solve a new
workflow problem. I've created several template scripts, which are available on your class CD and website, to help you
get started. The most basic template is called
Let's look at the first 4 lines of the script. These are what programmers call "comments." Comments are notes to yourself,
or others you share your scripts with, detailing information about script, and what each piece of code does. Notice that the
color of the comments is green. The ExtendScript Toolkit color-codes different pieces of text so you can tell comments
from code, and make the script more readable.
You create single-line comments by beginning the line with two forward slashes // or you can create double-line
comments by beginning with a forward slash and an asterisks /* and ending it will an asterisk and a forward slash */.
In the case of these four lines, I'm giving some information about the name of the script; when it was written, who wrote
it, and what version of the script is if I'm modifying and releasing new versions of the script.
In lines 6-9, I'm using a multi-line comment to give a detailed description of what my script does.
Up to this point, everything in this script has been a comment, and hopefully, this gives you a clue that comments are just
as important, if not more important, as working code. This will be common theme as we work on scripts. Commenting
will make working with or sharing scripts much easier.
The next chunk of code actually does something. Lines 11 and 12 describe what the code on line 13 does. In this case,
#target photoshop tells the script that it's been created to run in Photoshop if it's been double-clicked in the finder or
run from the ExtendScript Toolkit. Since scripts can run in other Creative Suite applications like Bridge, Illustrator, or
InDesign, so it's always good form to include this code in every script you write.
Line 15 is a comment for the method in line 16 app.bringToFront(); which brings Photoshop to the front when
a script is running. I like to include this method in all my scripts because I like to see my scripts do their magic. There's
something satisfying about watching Photoshop run under autopilot.
The next three chunks of comments are what I call section headers. I usually organize my scripts into 3 parts: SETUP,
MAIN, and FUNCTIONS.
In the SETUP section, I'll usually declare variables for my script. The MAIN section is where I'll put the working code.
The FUNCTIONS section is where I'll define any custom functions that I'll call in the MAIN section of the script. We'll
talk more about variables and custom functions as we start to write more complex scripts later on.
The alert(); method.
The first method we're going to learn is the alert(); method. An alert simply pops a dialog and displays some
information. I believe alerts are an invaluable tool for learning scripting and they will also come in handy later as you
start debugging more complex scripts. We'll use alerts for several of our first exercises.
For our first alert, we want to display the text "Hello, World!"
template.jsx script, lets first make a comment of what we want our alert to do. Then on the next line we'll type in
our method alert(); and pass in the string "Hello, World!" as an argument in between the parenthesis:
Let's test our script. Because I have the command #target photoshop in my script, I don't need to specify a target in the
ESTK. If I didn't have the command #target photoshop I'd have to manually select "Photoshop" from the pop-up in the
upper left-hand corner of the script window.
If the link icon next to the pop-up is broken and red, that usually means that Photoshop isn't launched and running. You
can either manually launch Photoshop or run your script and the ESTK will ask if you want to launch Photoshop or not.
If Photoshop is launched and your scripts fail, make sure you are targeting the right program. Often times, I'll forget to
include the command for #target photoshop and the script will try to run in the ESTK instead of Photoshop.
Click the play button in the upper right-hand corner of the script window to play your script.
Photoshop should come to the front and display a dialog with our "Hello, World!" text in it.
Once we've tested our script and we know it works, let's finish commenting and save our script
helloWorld.jsx to the
Running and Installing Scripts.
To run a script from the finder, simply double-click the script icon or drag the script onto the Photoshop application. If
you run a script this way, you will be asked whether you want to run the script or not.
To get your script to show up in Photoshop's File>Scripts menu, navigate to the Presets>Scripts folder inside the
Photoshop application folder on your hard drive and copy or place your script in the folder.
Mac: <hard drive>/Applications/Adobe Photoshop CS3/Presets/Scripts/
Windows: C:\Program Files\Adobe\Adobe Photoshop CS3\Presets\Scripts\
If Photoshop is already running, you'll need to quit and restart Photoshop for the script to show up in the menu.
When you run scripts from inside Photohop, you won't be asked whether you want the script to run or not, and the script
will just execute.
You can assign a keyboard shortcut to your script using the Edit>Edit Shortcuts… dialog. Tip: Don't use the option key
for a keyboard shortcut for a script. The option key puts the script into "debug" mode and will launch the ESTK. You
can also record an action that runs a script, and assign an F-key to the action to run it.
The Photoshop DOM.
Let's start exploring the Photoshop DOM. What is a DOM? DOM stands for Document Object Model. Document Object
Model is a programming interface that lets you interact with Photoshop to examine and manipulate the Photoshop
application, Photoshop documents, and the objects contained within the document.
One way to think of the DOM is to think of a series of folders put inside one another. You can imagine either physical
folders, or electronic folders on your hard drive or like a website path.
Each folder can contain various objects. Imagine the first, outside folder containing everything else in side it. That's
Photoshop or app.
Now imagine there's another folder inside the Photoshop folder. That's the Photoshop document you are working on, or
Now imagine there's another folder nested inside the document folder. That's the layer you are working on, or the
Now imagine the layer folder contains several sheets of paper in it. Each sheet of paper has a unique piece of information
about the layer: it's name, it's visibility, it's opacity, it's blendmode, whether it's locked or not, etc.
So, if I wanted to look at the sheet of paper with the current layers name, I'd need to go into the Photoshop folder, then
the document folder, then the layer folder, and look for the sheet with name on it. In the scripting world, the code
app.activeDocument.activeLayer.name would be how you get the current layer's name.
Let's have Photoshop show an alert with the current layer's name. Start with the
template.jsx script and add an alert, but
this time, let get the current layer's name and display that in the alert dialog:
Make sure there is a document open in Photoshop that contains some layers and one of the layers is selected.
Press play to test our script. Photoshop displays a dialog with the current layer's name on it. (
Using the Object Model Viewer to explore the Photoshop DOM.
Now that we know a little bit about how Photoshop Document Object Model works, let's take a look at Object Model
In the ExtendScript Toolkit, go to the Help menu and choose Adobe Photoshop CS3 Object Library. Let's navigate
through the object classes and inspect the properties and methods associated with each class.
It usually takes 3 clicks to navigate to each class.
First, click on Application in the class panel of the Object Model Viewer to examine all the properties and methods of the
Application or app.
Second, select activeDocument from the properties and methods panel.
Third, click on the hyperlink Document in the status panel. This selects the Document class in the class panel:
We can now dig deeper into the DOM, by selecting activeLayer in the properties and methods panel and click on
the Layer hyperlink in the status panel.
Notice how we can see all the properties and methods of the activeLayer in the properties and methods panel?
Properties are preceded by a blue icon and methods are preceded by a red icon. Methods are always followed by ().
We can see the property for name that we used in the previous example. Experiment alerting and setting the value of
some other properties such as blendMode, opacity, allLocked, and visibile. Note that some properties like
bounds, typename, and parent are "Read Only" meaning that you can get and alert their value, but you can't set
their value. (
Let's try working with some methods. We can remove(); the layer, which does the same thing as dragging the layer to
the trash button in the layers palette.
Create a new document with a few layers and try running a script that uses the remove(); method.
Solving a real-world problem with scripting.
A customer approached me and said that they recently discovered the command for File>Automate>Crop and Straighten
Photos for automating part of their workflow. They had placed several 4x5 pictures on their scanner and created one
image. Crop and Straighten Photos takes that image and automatically cuts out of the images and places them into their
own documents. They were amazed at the time they would save using this command, but they wished there was a way to
automatically name and save each of the resulting documents so they could process a folder of these multi-image scans.
I was able to write a script,
cropAndStraightenBatch.jsx, that solved this person's workflow in a matter of minutes. It's
a good script to learn from because it combines many, smaller useful scripting techniques into one larger workflow script.
As we build this script, you will learn about using variables, renaming & saving files, opening & closing files, using for
& while loops, and using the ScriptingListener plug-in.
Designing your script.
Before I begin scripting, I'll write out what I want my script to do as comments in plain English, or what programmers
call pseudo code. This is useful for laying out the groundwork of your script. It's also useful if you plan to hand off
instructions if you work with a programmer to help write your script. Here is my script outline:
// Make sure there are no open documents
// Ask the user to choose the folder of documents to process
// Ask the user to choose an output folder
// Open each document in the folder, one at a time and then process it (for loop)
// Store the name of the parent document we're going to crop and straighten from
// Crop and straighten the document, which will result in more than one open document, including the parent document
// Close the parent document without saving
// Process the remaining open documents until no documents are left open (while loop)
// Flatten the document in case the file type we want to save to requires a flat doc
// Save as a JPEG to the selected output folder
// Close the document
There's a good reason why I've formatted my comments with indentation the way I have and you'll see later in our lesson
why I've done this.
The ScriptingListener plug-in.
The first piece of code we need is for Crop and Straighten Photos. If we look in the Object Model Viewer, you'll discover
that there is no method for Crop and Straighten Photos in Photoshop's DOM. Don't distress. There are a lot of commands
in Photoshop that aren't in the DOM. That's where the ScriptingListener plug-in comes in handy.
Installing the ScriptingListener plug-in:
1) Quit Photoshop
2) Locate the ScriptingListener plug-in inside Photoshop's application folder: Adobe Photoshop CS3>Scripting
3) Copy the ScriptingListener plug-in into Photoshop's Plug-Ins folder: Adobe Photoshop CS3>Plug-Ins
2) Launch Photoshop
Using the ScriptingListener plug-in:
file named ScriptingListenerJS.log, which by default is saved to the desktop.
To determine if an operation is Actionable, double-click the ScriptingListenerJS.log file to launch the Console application.
Keep the Console window view of the ScriptingListenerJS.log visible as you are working. As you do operations in
Photoshop, you will see the log update if the operations you perform are Actionable. Painting, for example, is not an
Actionable operation. You can click 'Clear'' at any point to clear the entries in the log.
Try to get in the habit of recording one step at a time and commenting each operation so you know what it does. I
generally record the operation a few times with different settings so I can see where the settings change in the code. In
this case, I've determined that 72.000000 refers to the pixel position of the guide, and that "Vrtc" is used for
vertical guides and "Hrzn" is used for horizontal guides.
in your own arguments. In this case, we pass in an integer for pixelOffSet and the string "Vrtc", "Hrzn" for
Then you can simply call the function every time you want to use it:
To get the code for Crop and Straighten Photos, I'll open the sample file Vacation.tif inside Photoshop's application
Since there are no arguments, the function for Crop and Straighten Photos looks like this:
Save the script as
Conditionals are a very powerful feature of scripting. You can do an operation if certain conditions are met. A common
one is to run different actions if the document is wider than it is tall, or if the document is taller than it is wide, using an
Other common conditionals check to make sure the document is in the right color mode or bit depth, or the current layer
is a text or raster layer.
For our script, we want to make sure there aren't any open documents open before we run our script. It is a good idea to
do this to avoid damaging or losing unsaved changes to an open document, especially if your script does any sort of batch
Here is the code to check for open documents:
Save the script as
Another common use of scripting is to intelligently name/rename documents and save them.
For example, you might have a group of images of birds from your camera with a file name like "IMG_0918.tif"
and you want to save it as a ".jpg" file. First, we'll need to do a little bit of coding to slice off the original ".tif"
extension, in order to append on the new ".jpg" extension. You do this using the slice(); method. The slice
method expect two arguments, the startSlice and the endSlice. Imagine the string "IMG_0918.tif" is a
loaf of bread, and each character is a slice of bread. If I want to get rid of the last four characters ".tif" I need to
count back from the right edge of the word. So my endSlice number would be -4. Since I'm not slicing off anything
at the start, I use 0 for the startSlice number. So the code would look like this:
We can also slice off the useless prefix "IMG_" and add a new prefix, like "CraigsBirds_". For this, we're going
to count forward the number of characters we want to remove, so the startSlice number would be 4. So to slice off
that first four and last four characters, the code would look like this:
Now, we just need to add our new prefix and suffix. We're going to use the + sign operator to concatenate, or append, our
of using an operator:
Save your file as
Often times, when you are processing/exporting documents, you'll want to flatten the layers in your document in order to
make your document smaller and save it as a file type that doesn't support layers, like JPEG or PNG. If you don't flatten
before saving as a JPEG, it will pop a dialog and pause your script.
Documents you may be interested
Documents you may be interested