docs.sheetjs.com/docz/docs/03-demos/10-extensions/01-extendscript.md

438 lines
14 KiB
Markdown
Raw Normal View History

2022-05-30 05:04:05 +00:00
---
2023-04-16 07:21:15 +00:00
title: Photoshop and InDesign
2023-02-28 11:40:44 +00:00
pagination_prev: demos/cloud/index
pagination_next: demos/bigdata/index
2022-05-30 05:04:05 +00:00
---
2023-05-03 03:40:40 +00:00
import current from '/version.js';
2022-05-30 05:04:05 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-05-03 03:40:40 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-05-30 05:04:05 +00:00
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.
2023-06-06 10:01:12 +00:00
- "Common Extensibility Platform" (CEP): This was introduced in Creative Suite.
App automation uses ExtendScript, but integration logic uses modern JS.
2022-05-30 05:04:05 +00:00
2023-06-06 10:01:12 +00:00
- "Unified Extensibility Platform" (UXP): This is the current recommendation for
new Adobe CC extensions in supported apps (Photoshop 2021+ and InDesign 2022+)
2022-05-30 05:04:05 +00:00
2022-08-25 08:22:28 +00:00
This demo intends to cover parts relevant to SheetJS. General setup as well as
2022-05-30 05:04:05 +00:00
general Adobe considerations are not covered here. A basic familiarity with
extension development is assumed.
2023-04-16 07:21:15 +00:00
:::note
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
This demo was verified in the following deployments:
| App | Platform | Date |
|:----------|:-------------|:-----------|
| Photoshop | ExtendScript | 2023-04-15 |
| InDesign | ExtendScript | 2023-04-15 |
2023-04-30 12:27:09 +00:00
| InDesign | CEP | 2023-04-30 |
2023-05-03 03:40:40 +00:00
| InDesign | UXP | 2023-05-02 |
2023-04-16 07:21:15 +00:00
:::
## ExtendScript
[The "ExtendScript" build](/docs/getting-started/installation/extendscript) can
be included from a script in the same directory:
```js
#include "xlsx.extendscript.js"
```
2022-05-30 05:04:05 +00:00
### Reading Files
`XLSX.readFile` can directly accept an absolute URI:
```js
var workbook = XLSX.readFile("~/Documents/test.xlsx");
```
The path can be user-configurable using `File.openDialog`:
```js
/* 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);
```
<details open><summary><b>Complete Example</b> (click to hide)</summary>
2023-04-16 07:21:15 +00:00
<Tabs groupId="ccapp">
<TabItem value="photoshop" label="Photoshop">
2022-05-30 05:04:05 +00:00
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.
2023-04-16 07:21:15 +00:00
0) Download the [test workbook](pathname:///files/SheetJS.xlsb).
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
1) Download the following scripts:
2023-05-03 03:40:40 +00:00
<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.extendscript.js`}><code>xlsx.extendscript.js</code></a></li>
<li><a href={`https://docs.sheetjs.com/extendscript/parse.jsx`}><code>parse.jsx</code></a></li>
</ul>
2023-04-16 07:21:15 +00:00
and place in the scripts directory.
2) Restart Photoshop and open a file (or create a new one)
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
3) File > Scripts > parse and select the test workbook
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
4) An alert will confirm that the file was read and the author will be changed:
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
!["Changing Author" popup](pathname:///files/psparse.png)
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
5) Check the Author field of the document in File > File Info...
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
</TabItem>
<TabItem value="indesign" label="InDesign">
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
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.
0) Download the [test workbook](https://sheetjs.com/pres.xlsx) and
[InDesign template](pathname:///extendscript/Template.indd)
2022-05-30 05:04:05 +00:00
1) Download the following scripts:
2023-05-03 03:40:40 +00:00
<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.extendscript.js`}><code>xlsx.extendscript.js</code></a></li>
<li><a href={`https://docs.sheetjs.com/extendscript/esidparse.jsx`}><code>esidparse.jsx</code></a></li>
</ul>
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
Move to the scripts directory. To find the directory, activate Scripts panel
(Windows > Utilities > Scripts), click `☰`, and select "Reveal in Explorer".
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
2) Open the template
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
3) Activate the Scripts panel. Expand the "User" folder and double-click
`esidparse` in the list.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
4) In the "Select a spreadsheet" file picker, select the test file `pres.xlsx`
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
A new table will be added and the title will be the name of the first worksheet.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
</TabItem>
</Tabs>
2022-05-30 05:04:05 +00:00
</details>
### Writing Files
`XLSX.writeFile` can directly accept an absolute URI:
```js
XLSX.writeFile(workbook, "~/Documents/test.xlsx");
```
The path can be user-configurable using `File.saveDialog`:
```js
/* 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);
```
<details open><summary><b>Complete Example</b> (click to hide)</summary>
2023-04-16 07:21:15 +00:00
<Tabs groupId="ccapp">
<TabItem value="photoshop" label="Photoshop">
2022-05-30 05:04:05 +00:00
In this example, the script will show a dialog to select an output file. Once
2022-08-25 08:22:28 +00:00
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.
2022-05-30 05:04:05 +00:00
The PS author is available as `activeDocument.info.author`.
2023-04-16 07:21:15 +00:00
1) Download the following scripts:
2023-05-03 03:40:40 +00:00
<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.extendscript.js`}><code>xlsx.extendscript.js</code></a></li>
<li><a href={`https://docs.sheetjs.com/extendscript/write.jsx`}><code>write.jsx</code></a></li>
</ul>
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
and place in the scripts directory.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
2) Restart Photoshop and open a file (or create a new one)
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
3) File > File Info ... and confirm there is an Author. If not, set to `SheetJS`
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
4) File > Scripts > write and use the popup to select the Documents folder.
Enter `SheetJSPSTest.xlsx` and press "Save"
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
5) An alert will confirm that the file was created:
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
!["Created File" popup](pathname:///files/pswrite.png)
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
6) Open the generated `SheetJSPSTest.xlsx` file and compare to Photoshop author
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
</TabItem>
<TabItem value="indesign" label="InDesign">
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
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.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
0) Download the [InDesign document](pathname:///extendscript/Filled.indd)
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
1) Download the following scripts:
2023-05-03 03:40:40 +00:00
<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.extendscript.js`}><code>xlsx.extendscript.js</code></a></li>
<li><a href={`https://docs.sheetjs.com/extendscript/esidwrite.jsx`}><code>esidwrite.jsx</code></a></li>
</ul>
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
Move to the scripts directory. To find the directory, activate Scripts panel
(Windows > Utilities > Scripts), click `☰`, and select "Reveal in Explorer".
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
2) Open the document.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
3) 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"
4) An alert will confirm that the file was created. Open `SheetJSIDTest.xlsx`
and compare to the InDesign doc.
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
</TabItem>
</Tabs>
2022-05-30 05:04:05 +00:00
</details>
## CEP
2023-04-16 07:21:15 +00:00
[The standalone scripts](/docs/getting-started/installation/standalone) 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`:
```xml
<CEFCommandLine>
<Parameter>--allow-file-access</Parameter>
<Parameter>--allow-file-access-from-files</Parameter>
</CEFCommandLine>
```
The Base64 encoding is compatible with `type: "base64"`.
2023-04-25 00:51:32 +00:00
### Reading Files
2023-04-16 07:21:15 +00:00
The typical flow is to read data from CEP and pass the data into the host
ExtendScript context. The following snippet parses a workbook:
```js
/* 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" });
```
2023-04-25 00:51:32 +00:00
<details open><summary><b>Complete Example</b> (click to hide)</summary>
<Tabs groupId="ccapp">
<TabItem value="indesign" label="InDesign">
0) Download [`com.sheetjs.data.zip`](pathname:///extendscript/com.sheetjs.data.zip)
and extract to a `com.sheetjs.data` subdirectory.
2023-04-30 12:27:09 +00:00
1) Move the entire `com.sheetjs.data` folder to the CEP extensions folder:
- Windows `C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\`
- Macintosh `/Library/Application\ Support/Adobe/CEP/extensions`
2023-04-25 00:51:32 +00:00
If prompted, give administrator privileges.
2) Download and open [`Template.idml`](pathname:///extendscript/Template.idml)
3) Download <https://sheetjs.com/pres.xlsx>
4) Show the extension (in the menu bar, select Window > Extensions > SheetJS)
5) In the extension panel, click "Import from file" and select `pres.xlsx`
After "success" popup, the first worksheet should be written to the file.
</TabItem>
</Tabs>
</details>
### Writing Files
2023-04-16 07:21:15 +00:00
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:
```js
/* 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);
```
2022-05-30 05:04:05 +00:00
2023-04-25 00:51:32 +00:00
<details open><summary><b>Complete Example</b> (click to hide)</summary>
<Tabs groupId="ccapp">
<TabItem value="indesign" label="InDesign">
0) Download [`com.sheetjs.data.zip`](pathname:///extendscript/com.sheetjs.data.zip)
and extract to a `com.sheetjs.data` subdirectory.
2023-04-30 12:27:09 +00:00
1) Move the entire `com.sheetjs.data` folder to the CEP extensions folder:
- Windows `C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\`
- Macintosh `/Library/Application\ Support/Adobe/CEP/extensions`
2023-04-25 00:51:32 +00:00
If prompted, give administrator privileges.
2) Download and open [`Filled.idml`](pathname:///extendscript/Filled.idml)
3) Show the extension (in the menu bar, select Window > Extensions > SheetJS)
4) In the extension panel, click "Export to XLSX" and "Save" in the dialog.
5) A popup will display the path to the generated file. Open the new file.
</TabItem>
</Tabs>
</details>
2022-05-30 05:04:05 +00:00
## UXP
2023-05-03 03:40:40 +00:00
UXP uses scripts with `.psjs` (PS) or `.idjs` (InDesign) file extensions.
2023-04-16 07:21:15 +00:00
2023-05-03 03:40:40 +00:00
[The "Standalone" scripts](/docs/getting-started/installation/frameworks) can
be loaded directly in UXP scripts with `require`:
```js
// assuming xlsx.full.min.js is in the same folder as the idjs / psjs script
const XLSX = require("./xlsx.full.min.js");
```
2023-04-16 07:21:15 +00:00
Filesystem access is provided by the UXP storage module:
```js
2023-05-03 03:40:40 +00:00
const UXP = require("uxp");
const storage = UXP.storage, ufs = storage.localFileSystem;
2023-04-16 07:21:15 +00:00
```
2023-04-30 12:27:09 +00:00
### Reading Files
2022-05-30 05:04:05 +00:00
2023-04-16 07:21:15 +00:00
The `getFileForOpening` method resolves to a `File` object. Reading the file
with the `binary` format returns an `ArrayBuffer` object that can be parsed:
```js
/* 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);
```
2023-05-03 03:40:40 +00:00
<details open><summary><b>Complete Example</b> (click to hide)</summary>
<Tabs groupId="ccapp">
<TabItem value="indesign" label="InDesign">
0) Open the "Scripts Panel" folder.
To find this folder: Open the Scripts panel in InDesign (Window > Utilities >
Scripts). In the Scripts panel, right-click "User" and select "Reveal". This
will open a Finder (macOS) or Explorer (Windows) window. Open "Scripts Panel"
1) Download the following scripts:
<ul>
<li><a href="pathname:///extendscript/parse.idjs"><code>parse.idjs</code></a></li>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}><code>xlsx.full.min.js</code></a></li>
</ul>
Move them to the Scripts Panel folder.
2) Download and open [`Template.idml`](pathname:///extendscript/Template.idml)
3) Download <https://sheetjs.com/pres.xlsx>
4) In the Scripts Panel, double-click "parse". Select the downloaded `pres.xlsx`
in the file picker.
</TabItem>
</Tabs>
</details>
2023-04-30 12:27:09 +00:00
### Writing Files
2023-04-16 07:21:15 +00:00
The `getFileForSaving` method resolves to a `File` object. The workbook should
be written with `type: "buffer"` for compatibility with the `binary` format:
```js
/* 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 });
```
2023-05-03 03:40:40 +00:00
<details open><summary><b>Complete Example</b> (click to hide)</summary>
<Tabs groupId="ccapp">
<TabItem value="indesign" label="InDesign">
0) Open the "Scripts Panel" folder.
To find this folder: Open the Scripts panel in InDesign (Window > Utilities >
Scripts). In the Scripts panel, right-click "User" and select "Reveal". This
will open a Finder (macOS) or Explorer (Windows) window. Open "Scripts Panel"
1) Download the following scripts:
<ul>
<li><a href="pathname:///extendscript/write.idjs"><code>write.idjs</code></a></li>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}><code>xlsx.full.min.js</code></a></li>
</ul>
Move them to the Scripts Panel folder.
2) Download and open [`Filled.idml`](pathname:///extendscript/Filled.idml)
3) In the Scripts Panel, double-click "Write". Click "Save" in the dialog.
4) When the process finishes, open `SheetJSUXP.xlsx` and verify the contents.
</TabItem>
</Tabs>
</details>