FilePicker

A FilePicker is the user-facing system interface for selecting files or folders. The items chosen by the user are returned to the Omni Automation script as an array of URLs to the chosen items. The FilePicker class is supported by all Omni Automation applications on both iOS and macOS.

Constructors

An instance of the FilePicker class is created using the standard new constructor without any initial provided parameters.

var picker = new FilePicker()

Instance Properties

Control of the selection options for a FilePicker instance is accomplished by setting the values of the following properties:

For example, the following script will create a FilePicker instance that allows only the selection of a single text file:

var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [FileType.plainText]

Instance Methods

Once an instance of the FilePicker class has been created, it can be displayed to the user by calling the show() method on the instance.

var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [FileType.plainText] pickerPromise = picker.show()
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%0ApickerPromise%20%3D%20picker%2Eshow%28%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

Depending upon which operating system is used by the device running the script, the file picker will be presented as either a sheet (macOS) or an overlay dialog (iOS).

var aType = new FileType("public.plain-text") var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [aType] pickerPromise = picker.show()
omnigraffle://localhost/omnijs-run?script=try%7Bvar%20aType%20%3D%20new%20FileType%28%22public%2Eplain%2Dtext%22%29%0Avar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0Apicker%2Etypes%20%3D%20%5BaType%5D%0ApickerPromise%20%3D%20picker%2Eshow%28%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

Processing the FilePicker Results

When a file picker dialog is displayed, a JavaScript Promise object is returned to the script. This promise represents either the completion or cancellation of the user’s interaction with the file picker dialog, and if successful will contain an array of URL references to the items chosen by the user.

The Promise object can be processed by the script with standalone functions that process its success or cancelation, or through the inline appending of the then(…) method of the Promise class to the show() command (of the FilePicker class) to act as a receiver for the passed promise object.

In the following example of the inline technique, the call-back function within the then(…) method is passed the result of the successful completion of the picker dialog, which is an array of URLs to the chosen items. Note that the successful picker result is always an array even if only a single item was chosen.

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.

Here’s an example of using a file picker to select an open an existing OmniGraffle file and add a new canvas to it:

var picker = new FilePicker() picker.folders = false picker.multiple = false aFileType = new FileType("com.omnigroup.omnigraffle.graffle") picker.types = [aFileType] pickerPromise = picker.show() pickerPromise.then(function(urlsArray){ fileURL = urlsArray[0] app.openDocument( document, fileURL, function(doc,wasOpen){ cnvs = doc.portfolio.addCanvas() } ) })
omnigraffle://localhost/omnijs-run?script=try%7Bvar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0AaFileType%20%3D%20new%20FileType%28%22com%2Eomnigroup%2Eomnigraffle%2Egraffle%22%29%0Apicker%2Etypes%20%3D%20%5BaFileType%5D%0ApickerPromise%20%3D%20picker%2Eshow%28%29%0A%0ApickerPromise%2Ethen%28function%28urlsArray%29%7B%0A%09fileURL%20%3D%20urlsArray%5B0%5D%0A%09app%2EopenDocument%28%0A%09%09document%2C%0A%09%09fileURL%2C%0A%09%09function%28doc%2CwasOpen%29%7B%0A%09%09%09cnvs%20%3D%20doc%2Eportfolio%2EaddCanvas%28%29%0A%09%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-03  Set the properties of the new file picker.

 04  Create a new FileType instance of an OmniGraffle document.

 05  Assign the created file type as the value of the picker’s type property.

 06  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 the variable: pickerPromise

 08-17  The successful promise is processed using the then(…) method whose call-back function is automatically passed an array of the chosen item URLs.

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

 10-16  Use the openDocument(…) function of the Application class (passing in the URL to the chosen file) to open the file.

 13-15  The call-back function is passed as input a reference to the opened document.

 14  The document’s portfolio property is used to reference the document’s Portfolio object for calling the addCanvas() method in order to create a new canvas.

Using FilePicker with Actions

The use of a file picker can greatly enhance the usefulness of Omni Automation actions designed to import and integrate data or files into documents. For example, a file picker provides an excellent way for a user to select a text file whose contents are to be imported into a selected container or shape in OmniGraffle.

When integrating a file picker with an action, the use of the Promise object allows for independent handling of the promise success or cancellation events with the then(…) and cancel(…) instance functions of the Promise class.

You can use the following example action as a template for integration of a file picker into an Omni Automation action.

// ACTION METADATA (REQUIRED) /*{ "type": "action", "targets": ["omnigraffle"], "author": "Otto Automator", "identifier": "com.omni-automation.import-text-into-shape", "description": "Imports text from the chosen text file into the selected shape.", "label": "Import Text into Shape", "paletteLabel": "Import" }*/ // MAIN FUNCTION var _ = function(){ // CREATE ACTION OBJECT var action = new PlugIn.Action(function(selection, sender){ var selectedShape = selection.solids[0] // CONSTRUCT THE PICKER var picker = new FilePicker() picker.folders = false picker.multiple = false picker.types = [FileType.plainText] // SHOW THE PICKER AND RETURN JAVASCRIPT PROMISE pickerPromise = picker.show() // PROCESS THE PICKER RESULTS pickerPromise.then(function(urlsArray){ // RETRIEVE CHOSEN FILE REFERENCE fileURL = urlsArray[0] // IMPORT DATA FROM CHOSEN FILE fileURL.fetch(function(data) { selectedShape.text = data.toString() }) }) // PROCESS PICKER CANCELLATION pickerPromise.catch(function(error){ console.log("picker cancelled", error) }) }) // VALIDATE DOCUMENT SELECTION action.validate = function(selection, sender){ return (selection.solids.length == 1 ? true:false) } // RETURN ACTION OBJECT return action }(); _;

 02-10  The required metadata for the action file.

 12-52  The wrapping function that holds and executes the action.

 14-52  The new action instance with a call-back function that contains the executable code. By default, a reference to the current document selection is passed as input to the call-back function.

 45-47  The action validation function returns a boolean value based upon whether a single solid is selected in the document. If the validation value is true, then the action’s menu item becomes enabled in the application’s Automation menu.

 16  A reference to the selected graphic is stored in the variable: selectedShape

 19-22  a new FilePicker instance is created and its properties are set to allow the selection of only a single text file.

 25  The file picker is displayed to the user, resulting in a returned Promise object that gets stored in the variable: pickerPromise

 28-36  A successful completion of the picker dialog result in the then(…) function being called on the stored Promise object. By default, an array of URLs representing the user-selected items will be provided as input to the method’s call-back function.

 30  A reference to the sole selected item is stored in the variable: fileURL

 33-35  To retrieve the text contents of the chosen file, the fetch(…) method of the URL class is called upon the chosen file. The result of the fetching process will be the data from the file.

 34  The retrieved data is converted into a string using the standard toString() JavaScript method, and the resulting text is imported into the selected shape by setting the value of the shape’s text property to the converted data string.

 39-41  Should the picker dialog be cancelled, the catch(…) function is called on the Promise instance, allowing the script to perform any cleanup, logging, or handling of the error that may be necessary.

 50  The completed action object is returned to the wrapping function, which is then called and executed on line  52 

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