Module 6 • Lesson 2🧰 Building a Panel / Plugin

👤 The Goal: A Tool With a Face

Same logic, two front ends. On the right, a script you run by hunting through File ▸ Scripts ▸ Browse every time. On the left, a docked panel with a labeled button anyone on the team can click without knowing a line of code. The panel is the difference between a personal hack and a shippable tool. Drag the handle:

🧠 Mental Model: Three Files

A minimal UXP plugin is essentially three things: a manifest.json that tells Photoshop the plugin exists, what panel it adds, and what permissions it needs; an index.html that is the panel's UI (real HTML with UXP's spectrum widgets); and an index.js that runs when a button is clicked and does the Photoshop work. If you've built a tiny web page, you already know two-thirds of this.

The one Photoshop-specific rule: changes to the document must run inside executeAsModal (UXP's way of saying "I'm about to modify the doc, hold everything"). Inside that, you use the DOM (Lesson 6.1) or batchPlay. Everything else is ordinary front-end web development.

📄 The Manifest & the Panel

The manifest is the plugin's ID card. It names the plugin, declares a panel entrypoint, and requests permissions. Here's a minimal one, saved as manifest.json (JSON allows no comments, so copy only the braces and what's inside). "manifestVersion": 5 matters: without it Photoshop treats the file as an older manifest and ignores requiredPermissions. The one permission requested, localFileSystem: "request", is exactly what the export button needs to show a Save dialog, and nothing more:

{
  "manifestVersion": 5,
  "id": "com.ray.deliverykit",
  "name": "Delivery Kit",
  "version": "1.0.0",
  "main": "index.html",
  "host": { "app": "PS", "minVersion": "24.0.0" },
  "entrypoints": [
    { "type": "panel", "id": "main", "label": { "default": "Delivery Kit" },
      "minimumSize": { "width": 180, "height": 240 } }
  ],
  "requiredPermissions": { "localFileSystem": "request" }
}

The panel itself is just HTML. UXP provides Spectrum widgets (sp-button, sp-slider) that look native:

<!-- index.html -->
<sp-heading>Delivery Kit</sp-heading>
<sp-button id="exportBtn" variant="cta">Export web sizes</sp-button>
<script src="index.js"></script>

🔌 Wiring a Button

The logic file listens for the click and does the work inside executeAsModal. This handler bumps a document to a web size and exports it — the panel's whole job, in a dozen lines:

// index.js
const { app, core, action } = require("photoshop");
const { localFileSystem } = require("uxp").storage;

document.getElementById("exportBtn").addEventListener("click", async () => {
  // Ask where to save first. A file picker is a dialog, so keep it outside the modal scope.
  const file = await localFileSystem.getFileForSaving("web.jpg", { types: ["jpg"] });
  if (!file) { return; }                             // user cancelled

  await core.executeAsModal(async () => {            // required to modify the doc
    const doc = app.activeDocument;
    if (!doc) { return; }

    const longEdge = 2000;
    const scale = longEdge / Math.max(doc.width, doc.height);   // width/height are in pixels
    await doc.resizeImage(Math.round(doc.width * scale), Math.round(doc.height * scale));

    // DOM save: JPEG quality 0–12; the final true = save as a copy
    await doc.saveAs.jpg(file, { quality: 10 }, true);
  }, { commandName: "Export web size" });
});

Note that this resizes the open document itself; run it on a flattened copy, or undo afterward. When the DOM doesn't cover a command, you drop to batchPlay inside the same executeAsModal callback. The descriptor below is a stub, not runnable as-is: paste in a real one captured with the free Alchemist plugin while you perform the command by hand.

// STUB: replace the placeholder with a descriptor captured in Alchemist
await action.batchPlay([
  { /* _obj: "…", …captured descriptor… */ }
], {});

🛠️ Guided Build: A One-Button Panel

You'll scaffold the smallest plugin that does real work.

🧗 Now You: Solo Variation

🍳 Recipe Card: UXP Plugin

📓 Learning Journal

📝 Lesson Summary

🎉 What You've Accomplished

You turned a script into a tool with a face: a docked panel with a real button that resizes and exports the active document, loaded and debugged the way a developer would. That packaging step is what lets your automation reach people who will never open a code file.

❓ Common Questions at This Stage

🔭 Looking Ahead

You can give a tool a face; now you take the human out of the loop entirely. Next: Lesson 6.3: Pipelines — Headless Batch, APIs & QA, calling the Photoshop API and gating output with automated QA, the Module 6 deliverable.

✅ Before the Next Lesson

• Get the one-button panel loading, reloading with Watch, and exporting a real JPEG.
• Add a second button or a slider and debug at least one error in the console.
• Write your Learning Journal entry.

📚 Additional Resources

• Adobe: UXP for Photoshop (developer docs)
• Alchemist: batchPlay descriptor capture plugin