JavaScript Promises and the FilePicker

A JavaScript Promise is standard built-in object of the JavaScript language. The JavaScript Promise object represents the eventual completion (or failure) of an asynchronous operation, and its resulting value.

The use of JavaScript Promises with Omni Automation, and the FilePicker class in particular, enables a simpler design for your scripts and actions that are meant to respond to events, such as the presentation and completion of a file picker dialog.

Instead of writing complex functions containing multiple call-backs, using JavaScript promises, scripts can divided into functions that are individually called when file picker dialogs have been either approved or dismissed.

Promises are generated when a file picker is displayed using the show(…) method of the FilePicker class. The resulting promise is stored in a variable so that its functions for responding to the dialog approval or cancelation can be identified and isolated in the script.

Run the following example script and view the scripting console after closing the file picker dialog to see the results of the promise.

// FILEPICKER INSTANCE CREATED AND PROPERTIES SET var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [FileType.plainText] // PICKER PROMISE IS CREATED AND STORED WHEN PICKER IS DISPLAYED pickerPromise = picker.show() // PROMISE FUNCTION CALLED UPON PICKER APPROVAL pickerPromise.then(function(urlsArray){ aURL = urlsArray[0] // processing statements using url(s) console.log(aURL) }) // PROMISE FUNCTION CALLED UPON PICKER CANCELLATION pickerPromise.catch(function(error){ console.log("form cancelled", error.message) })
omnigraffle://localhost/omnijs-run?script=try%7Bvar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0Apicker%2Etypes%20%3D%20%5BFileType%2EplainText%5D%0A%0A%2F%2F%20PICKER%20PROMISE%20IS%20CREATED%20AND%20STORED%20WHEN%20PICKER%20IS%20DISPLAYED%0ApickerPromise%20%3D%20picker%2Eshow%28%29%0A%0A%2F%2F%20PROMISE%20FUNCTION%20CALLED%20UPON%20PICKER%20APPROVAL%0ApickerPromise%2Ethen%28function%28urlsArray%29%7B%0A%09aURL%20%3D%20urlsArray%5B0%5D%0A%09%2F%2F%20processing%20statements%20using%20url%28s%29%0A%09console%2Elog%28aURL%29%0A%7D%29%0A%0A%2F%2F%20PROMISE%20FUNCTION%20CALLED%20UPON%20PICKER%20CANCELLATION%0ApickerPromise%2Ecatch%28function%28error%29%7B%0A%09console%2Elog%28%22form%20cancelled%22%2C%20error%2Emessage%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

 02  Create a new empty file picker object and store it in a variable.

 03-05  Set the properties of the new file picker.

 08  Use the show(…) method of the FilePicker class to display the file picker dialog to the user. The result of this method is a new JavaScript Promise object that is stored in a variable.

 11-15  The then(…) method of the Promise class is used to process the promise upon approval of the file picker dialog. An array of URLs for the chosen items is passed into the method’s call-back function.

 18-20  A function that is called if the file picker dialog is cancelled.

Inline Promise Processing

As shown in the example above, the result of using the show(…) method to display a file picker dialog is a JavaScript promise object, which can then be processed using the then(…) or catch(…) functions depending on whether the dialog was approved or canceled.

If processing a canceled picker is not necessary for your script, you can streamline the script coding by appending the then(…) function to the show(…) function as shown in the example below. Functionally, this technique is the same as processing a promise object stored in a variable. The callback function within the then(…) function still receives the array of URLs chosen by the user in the file picker dialog.

var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [FileType.plainText] picker.show().then(function(urlsArray){ aURL = urlsArray[0] aURL.fetch(function(data){ console.log(data.toString()) }) })
omnigraffle://localhost/omnijs-run?script=try%7Bvar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0Apicker%2Etypes%20%3D%20%5BFileType%2EplainText%5D%0Apicker%2Eshow%28%29%2Ethen%28function%28urlsArray%29%7B%0A%09aURL%20%3D%20urlsArray%5B0%5D%0A%09aURL%2Efetch%28function%28data%29%7B%0A%09%09console%2Elog%28data%2EtoString%28%29%29%0A%09%7D%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

 01  Create a new empty file picker object and store it in a variable.

 02-04  Set the properties of the new file picker.

 05  Use the show(…) method of the FilePicker class to display the file picker dialog to the user. The result of this method is a new JavaScript Promise object that is then processed by the appended then(…) function.

 06  A URL object is extracted from the URLs array passed by the promise as input to the call-back function.

 07-09  The fetch(…) method of the URL class is used to read the file represented by the extracted URL.

Promise Documentation

JavaScript Promises offer a high degree of customization beyond the basic use with forms shown here. Detailed information regarding JavaScript Promises is available at:

UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER