Module 6 • Lesson 1💻 JavaScript / UXP Scripting in Depth

👤 The Goal: Steps That Think

An Action does the same thing every time; a script decides. On the right, an Action replays fixed steps. Its one built-in branch (Insert Conditional, such as Document Is Landscape) can only choose which Action to play; it can't count layers, do math, or decide anything else per file. On the left, a script loops, checks conditions, and produces different, correct output per file. Logic is the whole difference. Drag the handle:

🧠 Mental Model: The DOM

A script drives Photoshop through its Document Object Model — a tree of objects you read and change. At the top is app; it has documents; each document has layers, a width, a color mode; each layer has a name, opacity, blend mode, bounds. Scripting is just walking that tree and setting properties: "for each document, for each layer, if the name starts with 'BG', hide it." If you can describe the task as objects and properties, you can script it.

⚖️ ExtendScript vs UXP

Two scripting worlds coexist. ExtendScript (.jsx) is the legacy engine: old-JavaScript, a mature DOM, run instantly via File ▸ Scripts ▸ Browse — perfect for quick automation and the vast library of existing scripts online. UXP is the modern platform: current JavaScript and async APIs. It comes in two forms: standalone UXP scripts (.psjs, Photoshop 23.5+) that also run from File ▸ Scripts ▸ Browse, and plugins with real HTML/CSS panels (Lesson 6.2). For a one-off batch job, a .jsx you find online is often the fastest path; for new code you'll maintain, write a .psjs; for a tool with a UI, build a UXP plugin.

🧾 A Script That Loops & Decides

Here is a complete, readable ExtendScript that does something no Action can: loop every open document, branch on its orientation, and export each at the right crop and multiple sizes. Read it top to bottom — you can already follow every line.

// smart-export.jsx  (File ▸ Scripts ▸ Browse to run)
var sizes = [2000, 1000, 500];              // long-edge sizes to export, in pixels
var outDir = new Folder("~/Desktop/export");
if (!outDir.exists) outDir.create();

var oldUnits = app.preferences.rulerUnits;  // remember the user's units...
app.preferences.rulerUnits = Units.PIXELS;  // ...so all the math below is in pixels

for (var d = 0; d < app.documents.length; d++) {
    var doc = app.documents[d];
    var w = doc.width.value, h = doc.height.value;
    var ratio = (w === h) ? 1 : (w > h ? (16/9) : (4/5));   // a decision Actions can't make

    for (var s = 0; s < sizes.length; s++) {
        var copy = doc.duplicate();             // work on a throwaway copy
        copy.convertProfile("sRGB IEC61966-2.1", Intent.RELATIVECOLORIMETRIC, true, false); // web color
        copy.bitsPerChannel = BitsPerChannelType.EIGHT;   // JPEG can't hold 16-bit
        cropToRatio(copy, ratio);
        var scale = sizes[s] / Math.max(copy.width.value, copy.height.value);
        copy.resizeImage(Math.round(copy.width.value * scale), Math.round(copy.height.value * scale));

        var name = doc.name.replace(/\.[^.]+$/, "") + "_" + sizes[s] + ".jpg";
        var opt = new JPEGSaveOptions(); opt.quality = 10;
        copy.saveAs(new File(outDir + "/" + name), opt, true);
        copy.close(SaveOptions.DONOTSAVECHANGES);
    }
}
app.preferences.rulerUnits = oldUnits;      // put the user's units back
alert("Exported " + app.documents.length + " docs × " + sizes.length + " sizes.");

function cropToRatio(doc, r) {                 // reusable helper
    var w = doc.width.value, h = doc.height.value;
    if (w / h > r) { var nw = h * r; doc.crop([ (w-nw)/2, 0, (w+nw)/2, h ]); }
    else            { var nh = w / r; doc.crop([ 0, (h-nh)/2, w, (h+nh)/2 ]); }
}

Two lines at the top matter more than they look. ExtendScript measures in whatever ruler units the user has set, so a script that assumes pixels breaks on a machine set to inches; saving and restoring rulerUnits makes it portable. And because this course's masters are 16-bit and wide-gamut, each copy is converted to sRGB and 8-bit before the JPEG save, which JPEG requires.

The same idea in UXP: a .psjs script

Since Photoshop 23.5, UXP scripts saved with the .psjs extension also run from File ▸ Scripts ▸ Browse, no plugin required. The code is modern JavaScript, the API is asynchronous, and anything that changes a document must run inside core.executeAsModal(), which gives your script exclusive control while it works. Here is the "hide every layer starting with ref" rule as a UXP script:

// hide-ref-layers.psjs  (File ▸ Scripts ▸ Browse, Photoshop 23.5+)
const { app, core } = require("photoshop");

async function hideRefLayers() {
    const doc = app.activeDocument;
    let hidden = 0;
    for (const layer of doc.layers) {          // top-level layers only
        if (layer.name.startsWith("ref")) {
            layer.visible = false;
            hidden++;
        }
    }
    return hidden;
}

// Anything that edits a document must run inside executeAsModal.
core.executeAsModal(hideRefLayers, { commandName: "Hide ref layers" })
    .then(n => app.showAlert(`Hid ${n} layer(s).`))
    .catch(e => app.showAlert("Failed: " + e.message));

Compare it with the ExtendScript above: the same DOM idea (app → document → layers → properties), with modern syntax such as const, for…of, and template strings, plus the executeAsModal wrapper. That wrapper is the one UXP rule you can't skip.

🛠️ Guided Build: Adapt a Script

Start from the script above (or any script you find) and make it yours.

var log = [];                          // before the loop
// inside the per-size loop:
var copy = null;
try {
    copy = doc.duplicate();
    /* ...the convert / crop / resize / save work... */
} catch (e) {
    log.push(doc.name + " @" + sizes[s] + ": " + e.message);   // note it and keep going
} finally {
    if (copy) copy.close(SaveOptions.DONOTSAVECHANGES);      // never leave a copy open
}
// after the loop:
if (log.length) {
    var f = new File(outDir + "/errors.txt");
    f.open("w"); f.write(log.join("\n")); f.close();
}

🧗 Now You: Solo Variation

🍳 Recipe Card: Scripting

📓 Learning Journal

📝 Lesson Summary

🎉 What You've Accomplished

You ran, edited, and extended a real script that makes decisions no Action can, then made it robust enough to trust on a folder of client files. You also saw the same idea in modern UXP, which is the foundation for the panel you build next.

❓ Common Questions at This Stage

🔭 Looking Ahead

A script runs from a menu; a tool has a face. Next: Lesson 6.2: Building a Panel / Plugin, where UXP turns your scripts into a real HTML/CSS panel with buttons, docked inside Photoshop.

✅ Before the Next Lesson

• Keep your adapted smart-export.jsx with its try/catch log; you'll reuse it.
• Run the .psjs example on a test file and change the rule it uses.
• Write your Learning Journal entry.

📚 Additional Resources

• Adobe: Photoshop UXP API reference
• Adobe: Scripting in Photoshop