docs.sheetjs.com/docz/docs/03-demos/10-extensions/01-extendscript.md
2023-04-16 03:21:15 -04:00

9.2 KiB

title pagination_prev pagination_next
Photoshop and InDesign demos/cloud/index demos/bigdata/index

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Photoshop, InDesign and other Adobe Creative Suite applications offer extension support. Over the years there have been a few different JavaScript platforms:

  • "ExtendScript": This uses an old JavaScript dialect but is supported in older versions of Creative Suite and Creative Cloud.

  • "CEP": This was recommended in CS6 but eventually deprecated.

  • "UXP": This is the current Adobe recommendation for new CC extensions.

This demo intends to cover parts relevant to SheetJS. General setup as well as general Adobe considerations are not covered here. A basic familiarity with extension development is assumed.

:::note

This demo was verified in the following deployments:

App Platform Date
Photoshop ExtendScript 2023-04-15
InDesign ExtendScript 2023-04-15
InDesign CEP 2023-04-15
InDesign UXP 2023-04-15

:::

ExtendScript

The "ExtendScript" build can be included from a script in the same directory:

#include "xlsx.extendscript.js"

Reading Files

XLSX.readFile can directly accept an absolute URI:

var workbook = XLSX.readFile("~/Documents/test.xlsx");

The path can be user-configurable using File.openDialog:

/* Show File Picker */
var thisFile = File.openDialog("Select a spreadsheet");
if(!thisFile) { alert("File not found!"); return; }

/* Read file from disk */
var workbook = XLSX.readFile(thisFile.absoluteURI);
Complete Example (click to hide)

In this example, the script will show a dialog to select a file. After reading the file, the workbook Author property will be extracted and the Photoshop doc author (activeDocument.info.author) will be changed accordingly.

  1. Download the test workbook.

  2. Download the following scripts:

and place in the scripts directory.

  1. Restart Photoshop and open a file (or create a new one)

  2. File > Scripts > parse and select the test workbook

  3. An alert will confirm that the file was read and the author will be changed:

"Changing Author" popup

  1. Check the Author field of the document in File > File Info...

In this example, the script will show a dialog to select a file. After reading the file, the script will store data in the document:

  • The first Text object in the "Title" TextFrame (the name of the TextFrame in the Layers window is "Title") will be set to the name of the first worksheet.

  • The data from the first sheet will be added to the "Table Frame" TextFrame.

  1. Download the test workbook and InDesign template

  2. Download the following scripts:

Move to the scripts directory. To find the directory, activate Scripts panel (Windows > Utilities > Scripts), click , and select "Reveal in Explorer".

  1. Open the template

  2. Activate the Scripts panel. Expand the "User" folder and double-click esidparse in the list.

  3. In the "Select a spreadsheet" file picker, select the test file pres.xlsx

A new table will be added and the title will be the name of the first worksheet.

Writing Files

XLSX.writeFile can directly accept an absolute URI:

XLSX.writeFile(workbook, "~/Documents/test.xlsx");

The path can be user-configurable using File.saveDialog:

/* Show File Picker */
var thisFile = File.saveDialog("Select an output file", "*.xlsx;*.xls");
if(!thisFile) { alert("File not found!"); return; }

/* Write file to disk */
XLSX.writeFile(workbook, thisFile.absoluteURI);
Complete Example (click to hide)

In this example, the script will show a dialog to select an output file. Once selected, the library will create a new workbook with one worksheet. Cell A1 will be "Author" and cell B1 will be the active Photoshop document Author. The PS author is available as activeDocument.info.author.

  1. Download the following scripts:

and place in the scripts directory.

  1. Restart Photoshop and open a file (or create a new one)

  2. File > File Info ... and confirm there is an Author. If not, set to SheetJS

  3. File > Scripts > write and use the popup to select the Documents folder. Enter SheetJSPSTest.xlsx and press "Save"

  4. An alert will confirm that the file was created:

"Created File" popup

  1. Open the generated SheetJSPSTest.xlsx file and compare to Photoshop author

In this example, the script will show a dialog to select an output file. Once selected, the library will scan all text frames for table objects. Each table object will be scanned and a new worksheet will be created.

  1. Download the InDesign document

  2. Download the following scripts:

Move to the scripts directory. To find the directory, activate Scripts panel (Windows > Utilities > Scripts), click , and select "Reveal in Explorer".

  1. Open the document.

  2. Activate the Scripts panel. Expand the "User" folder and double-click esidwrite in the list. Use the popup to select the Documents folder. Enter SheetJSIDTest.xlsx and press "Save"

  3. An alert will confirm that the file was created. Open SheetJSIDTest.xlsx and compare to the InDesign doc.

CEP

The standalone scripts can be added to CEP extension HTML. It should be downloaded from the CDN and included in the extension.

For performing file operations in CEP extensions, NodeJS is not required! The manifest must include the following flags to enable cep.fs:

<CEFCommandLine>
  <Parameter>--allow-file-access</Parameter>
  <Parameter>--allow-file-access-from-files</Parameter>
</CEFCommandLine>

The Base64 encoding is compatible with type: "base64".

Reading Files

The typical flow is to read data from CEP and pass the data into the host ExtendScript context. The following snippet parses a workbook:

/* show file picker (single file, no folders) */
const fn = cep.fs.showOpenDialogEx(false, false, "Select File", "", ["xlsx"]);
/* read data as Base64 string */
const data = cep.fs.readFile(fn.data[0], cep.encoding.Base64);
/* parse with SheetJS */
const wb = XLSX.read(data.data, { type: "base64" });

Writing Files

The typical flow is to invoke a function with CSInterface#evalScript that returns data from the host ExtendScript context. The callback should build the workbook and initiate a file save. The following snippet saves a workbook:

/* generate XLSX as base64 string */
const b64 = XLSX.write(wb, {type:"base64", bookType: "xlsx"})
/* show file picker */
const fn = cep.fs.showSaveDialogEx("Save File","",["xlsx"],"SheetJSIDCEP.xlsx");
/* write file */
cep.fs.writeFile(fn.data, b64, cep.encoding.Base64);

UXP

UXP uses bundled scripts with .psjs (PS) or .idjs (InDesign) extension. The official samples use webpack to build bundles.

The "Frameworks" instructions describe installation steps for traditional webpack projects.

Filesystem access is provided by the UXP storage module:

const storage = require("uxp").storage;
const ufs = storage.localFileSystem;

Reading Files

The getFileForOpening method resolves to a File object. Reading the file with the binary format returns an ArrayBuffer object that can be parsed:

/* show file picker (single file, no folders) */
const file = await ufs.getFileForOpening({ types: ["xlsx", "xls", "xlsb"] });
/* read data into an ArrayBuffer */
const ab = await file.read({ format: storage.formats.binary });
/* parse with SheetJS */
const wb = XLSX.read(ab);

Writing Files

The getFileForSaving method resolves to a File object. The workbook should be written with type: "buffer" for compatibility with the binary format:

/* generate XLSX with type: "buffer" */
const buf = XLSX.write(wb, { type: "buffer", bookType: "xlsx" });
/* show file picker */
const file = await ufs.getFileForSaving("SheetJSUXP.xlsx");
/* write data */
await file.write(buf, { data: storage.formats.binary });