How to read a file

This tutorial will show you how an XD plugin can read in a file from the file system. As one of example of what you can do with a file, we'll extract text from the file and add that text to the scenegraph.

Prerequisites#

Basic knowledge of HTML, CSS, and JavaScript.
Quick Start Tutorial
Debugging Tutorial

Development Steps#

Info Complete code for this plugin can be found on GitHub.

1. Prepare your plugin scaffold#

First, edit the manifest file for the plugin you created in our Quick Start Tutorial.

Replace the uiEntryPoints field of the manifest with the following:

"uiEntryPoints": [
    {
        "type": "menu",
        "label": "Insert Text From File",
        "commandId": "insertTextFromFileCommand"
    }
]
Copied to your clipboard
1"uiEntryPoints": [
2    {
3        "type": "menu",
4        "label": "Insert Text From File",
5        "commandId": "insertTextFromFileCommand"
6    }
7]

If you're curious about what each entry means, see the manifest documentation, where you can also learn about all manifest requirements for a plugin to be published in the XD Plugin Manager.

Then, update your main.js file, mapping the manifest's commandId to a handler function.

Replace the content of your main.js file with the following code (note the presence of the async keyword, which we'll look at in a later step):

async function insertTextFromFileHandler(selection) {
  // The body of this function is added later
}

module.exports = {
  commands: {
    insertTextFromFileCommand: insertTextFromFileHandler,
  },
};
Copied to your clipboard
1async function insertTextFromFileHandler(selection) {
2  // The body of this function is added later
3}
4
5module.exports = {
6  commands: {
7    insertTextFromFileCommand: insertTextFromFileHandler,
8  },
9};

The remaining steps in this tutorial describe additional edits to the main.js file.

2. Require in XD API dependencies#

For this tutorial, we need access to two XD scenegraph dependencies and one UXP dependency.

Add the following lines to the top of your main.js file:

// Add this to the top of your main.js file
const { Text, Color } = require("scenegraph");
const fs = require("uxp").storage.localFileSystem;
Copied to your clipboard
1// Add this to the top of your main.js file
2const { Text, Color } = require("scenegraph");
3const fs = require("uxp").storage.localFileSystem;

Now the Text and Color classes are required in and ready to be used, as well as UXP's local file system provider.

3. Create a handler function#

Our plugin will allow the user to pick a file from the system file picker, read that file's contents, and add the contents to a text object on the scenegraph.

Each of the numbered comments are explained below the code:

async function insertTextFromFileHandler(selection) {
  // [1]
  const aFile = await fs.getFileForOpening({ types: ["txt"] }); // [2]
  if (!aFile) return; // [3]

  const contents = await aFile.read(); // [4]

  const text = new Text(); // [5]
  text.text = contents;
  text.styleRanges = [
    {
      length: contents.length,
      fill: new Color("#0000ff"),
      fontSize: 12,
    },
  ];

  selection.insertionParent.addChild(text); // [6]
  text.moveInParentCoordinates(10, 30);
}
Copied to your clipboard
1async function insertTextFromFileHandler(selection) {
2  // [1]
3  const aFile = await fs.getFileForOpening({ types: ["txt"] }); // [2]
4  if (!aFile) return; // [3]
5
6  const contents = await aFile.read(); // [4]
7
8  const text = new Text(); // [5]
9  text.text = contents;
10  text.styleRanges = [
11    {
12      length: contents.length,
13      fill: new Color("#0000ff"),
14      fontSize: 12,
15    },
16  ];
17
18  selection.insertionParent.addChild(text); // [6]
19  text.moveInParentCoordinates(10, 30);
20}

This example uses XD's asynchronous Filo I/O APIs, so the handler function must be declared as an async method. To learn more about async support in XD plugin APIs, see our document on sync and async support.
A file picker dialog is displayed, and the function waits for the user to select a text file. The selected file is assigned to aFile. The #getFileForOpening method is asynchronous, so the await keyword is used.
If aFile is undefined (because the user did not select a file), then plugin exits.
The contents of the file is read in, and returned as a string. See below for more detail. The #read method is asynchronous, so the await keyword is used.
The contents of the string is added to a Text object. For details on Text properties, see the "How to style text" tutorial.
The text object is added to and positioned on the selected artboard.