JavaScript Promises and Forms

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 forms 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 form dialog.

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

Promises are generated when a form is displayed using the show(…) method of the Form 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 form dialog to see the results of the form promise.

// Basic Form Promise Functions exampleForm = new Form() textInputField = new Form.Field.String( "textInput", "Field Label", null ) exampleForm.addField(textInputField) // FORM PROMISE IS CREATED AND STORED WHEN DIALOG SHOWN formPrompt = "Form prompt" buttonTitle = "Approval Button Title" formPromise = exampleForm.show(formPrompt, buttonTitle) // PROMISE FUNCTION CALLED UPON DIALOG APPROVAL formPromise.then(function(formObject){ textInput = formObject.values["textInput"] // processing statements using form data console.log(textInput) }) // PROMISE FUNCTION CALLED UPON DIALOG CANCELLATION formPromise.catch(function(error){ console.log("form cancelled", error.message) })
omnigraffle://localhost/omnijs-run?script=try%7BexampleForm%20%3D%20new%20Form%28%29%0A%0AtextInputField%20%3D%20new%20Form%2EField%2EString%28%0A%09%22textInput%22%2C%0A%09%22Field%20Label%22%2C%0A%09null%0A%29%0A%0AexampleForm%2EaddField%28textInputField%29%0A%0A%2F%2F%20FORM%20PROMISE%20IS%20CREATED%20AND%20STORED%0AformPromise%20%3D%20exampleForm%2Eshow%28%22Form%20prompt%22%2C%22Approval%20Button%20Title%22%29%0A%0A%2F%2F%20PROMISE%20FUNCTION%20CALLED%20UPON%20DIALOG%20APPROVAL%0AformPromise%2Ethen%28function%28formObject%29%7B%0A%09textInput%20%3D%20formObject%2Evalues%5B%22textInput%22%5D%0A%09%2F%2F%20processing%20statements%20using%20form%20data%0A%09console%2Elog%28textInput%29%0A%7D%29%0A%0A%2F%2F%20PROMISE%20FUNCTION%20CALLED%20UPON%20DIALOG%20CANCELLATION%0AformPromise%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

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

 03-07  Create a new form element (text input) and store in a variable.

 04  The identifying key for the created form element.

 09  Use the addField(…) method of the Form class to add the created form element to the empty form object.

 12  Use the show(…) method of the Form class to display the form dialog to the user. The result of this method is a new JavaScript Promise object that is stored in a variable.

 15-19  The then(…) method of the Promise class is used to process the promise upon approval of the form dialog. A form object containing the form settings is passed into the method’s call-back function.

 16  The value of the values property of the form object is a record of each form element key and its corresponding value.

 22-24  A function that is called if the form dialog is cancelled.

example-form-omnigraffle

NOTE: 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