The Alert Dialog

The automation routines in scripts, actions, and libraries may require communication with the user. The alert dialog is a handy tool for both conveying information to and for eliciting a choice from the person running the automation. The following describes how to use the Alert() object.

NOTE: The examples on this page are designed to work with both the macOS and iOS versions of the OmniGraffle application. However, the alert() object works the same in all Omni applications.

Alert Dialog: Informational

A basic use of the alert dialog is to inform the user about the status of a script. The standard alert dialog displays a title and message (macOS and iOS):

var alert = new Alert('Title','Message') alert.show(function(result){})
omnigraffle:///omnijs-run?script=var%20alert%20%3D%20new%20Alert('Title'%2C'Message')%0Aalert.show(function(result)%7B%7D)
basic-alert Screenshot

When creating a new instance of the Alert() class (see line 1 above), there are two required parameters: the dialog title and the dialog message.

To display the alert dialog, the show() method (command) is executed with the created alert object (line 2). This method takes a call-back function as its default parameter. The call-back function returns the result of the user action in terminating the dialog by selecting a button. In the example shown above, the function is empty as there is only one option the user can select.

Here’s a version of the basic script designed to stop the host script after the user terminates the dialog, by throwing an error. It is written as a single-line script:

new Alert('Title','Message').show(function(result){throw new Error('script cancelled')})
omnigraffle:///omnijs-run?script=new%20Alert('Title'%2C'Message').show(function(result)%7Bthrow%20new%20Error('script%20cancelled')%7D)

The Alert Dialog: Two Options

Well-designed automation tools may, on occasion, require the user to indicate their preference in the way a task is to processed. For example, do they want a new graphic to be created on the current layer or a new layer? The Alert dialog provides a way for the script user to indicate their choice.

The Alert dialog may contain up to three buttons (options). To add buttons to the dialog, create and alert object and apply the addOption(buttonTitle) method to the alert object. The addOption() method takes a single parameter, which is the title displayed in the button.

As mentioned previously, the show() method, which is applied to the alert object, takes a callback function as its parameter. The callback function is passed the result of the dialog, indicated as an integer with 0 being the rightmost button, 1 being the button to its left, and so on.

Inclusion of a simple conditional statement (if…) in the callback function, enables the script to assign an action for each the buttons.

alert-two-options Screenshot
var alert = new Alert("Title", "Message") alert.addOption("Button 1") alert.addOption("Button 2") alert.show(function(result){ if (result == 0){ console.log("Button 1") } else { console.log("Button 2") } })
omnigraffle:///omnijs-run?script=var%20alert%20%3D%20new%20Alert(%22Title%22%2C%20%22Message%22)%0Aalert.addOption(%22Button%201%22)%0Aalert.addOption(%22Button%202%22)%0Aalert.show(function(result)%20%7B%0A%09if%20(result%20%3D%3D%200)%20%7B%0A%09%09console.log(%22Button%201%22)%0A%09%7D%20else%20%7B%0A%09%09console.log(%22Button%202%22)%0A%09%7D%0A%7D)

(below) A basic use of the two-button alert dialog is for displaying a confirmation dialog to the user. If they tap|click the button to stop the script, an error is thrown, otherwise the script continues.

var alert = new Alert("Confirmation", "WARNING: Using automation tools may change your computer life for the better!\n\nShould the script continue?") alert.addOption("Continue") alert.addOption("Stop") alert.show(function(result){ if (result == 0){ console.log("Continue script") } else { throw new Error('script cancelled') } })
omnigraffle:///omnijs-run?script=var%20alert%20%3D%20new%20Alert(%22Confirmation%22%2C%20%22WARNING%3A%20Using%20automation%20tools%20may%20change%20your%20computer%20life%20for%20the%20better!%5Cn%5CnShould%20the%20script%20continue%3F%22)%0Aalert.addOption(%22Continue%22)%0Aalert.addOption(%22Stop%22)%0Aalert.show(function(result)%7B%0A%09if%20(result%20%3D%3D%200)%7B%0A%09%09console.log(%22Continue%20script%22)%0A%09%7D%20else%20%7B%0A%09%09throw%20new%20Error('script%20cancelled')%0A%09%7D%0A%7D)
confirmation-dialog Screenshot

In case you haven’t noticed, in macOS, the rightmost button is always the default button, activated via the keyboard (Return or Enter keys).

The Alert Dialog: Three Options

The 3-button alert dialog is similar to the 2-button alert dialog, with the addition of another option and conditional.

3-buton-basic Screenshot
var alert = new Alert("Title", "Message") alert.addOption("A") alert.addOption("B") alert.addOption("C") alert.show(function(result){ if (result == 0){ console.log("A") } else if (result == 1){ console.log("B") } else { console.log("C") } })
omnigraffle:///omnijs-run?script=var%20alert%20%3D%20new%20Alert(%22Title%22%2C%20%22Message%22)%0Aalert.addOption(%22A%22)%0Aalert.addOption(%22B%22)%0Aalert.addOption(%22C%22)%0Aalert.show(function(result)%7B%0A%09if%20(result%20%3D%3D%200)%7B%0A%09%09console.log(%22A%22)%0A%09%7D%20else%20if%20(result%20%3D%3D%201)%7B%0A%09%09console.log(%22B%22)%0A%09%7D%20else%20%7B%0A%09%09console.log(%22C%22)%0A%09%7D%0A%7D)

The 3-button alert dialog is often used to present an either/or choice with the option to stop the script.

alert-three-options Screenshot
alertTitle = "Graphic Placement" alertMessage = "Should the graphic be placed on the current canvas or a new canvas?" alert = new Alert(alertTitle, alertMessage) alert.addOption("Current") alert.addOption("New") alert.addOption("Cancel") alert.show(function(result){ if (result == 0){ aRect = new Rect(0, 0, 200, 200) cnvs = document.windows[0].selection.canvas cnvs.addShape('Circle', aRect) } else if (result == 1){ cnvs = addCanvas() aRect = new Rect(0, 0, 200, 200) cnvs.addShape('Circle', aRect) } else { throw new Error('script cancelled') } })
omnigraffle:///omnijs-run?script=alertTitle%20%3D%20%22Graphic%20Placement%22%0AalertMessage%20%3D%20%20%22Should%20the%20graphic%20be%20placed%20on%20the%20current%20canvas%20or%20a%20new%20canvas%3F%22%0Aalert%20%3D%20new%20Alert%28alertTitle%2C%20alertMessage%29%0Aalert%2EaddOption%28%22Current%22%29%0Aalert%2EaddOption%28%22New%22%29%0Aalert%2EaddOption%28%22Cancel%22%29%0Aalert%2Eshow%28function%28result%29%7B%0A%09if%20%28result%20%3D%3D%200%29%7B%0A%09%09aRect%20%3D%20new%20Rect%280%2C%200%2C%20200%2C%20200%29%0A%09%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09%09cnvs%2EaddShape%28%27Circle%27%2C%20aRect%29%0A%09%7D%20else%20if%20%28result%20%3D%3D%201%29%7B%0A%09%09aCanvas%20%3D%20addCanvas%28%29%0A%09%09aRect%20%3D%20new%20Rect%280%2C%200%2C%20200%2C%20200%29%0A%09%09aCanvas%2EaddShape%28%27Circle%27%2C%20aRect%29%0A%09%7D%20else%20%7B%0A%09%09throw%20new%20Error%28%27script%20cancelled%27%29%0A%09%7D%0A%7D%29

Summary

The Alert() object and show() method are very useful tools for a scripter. In general, it is good scripting design to include confirmation or introductory alerts in scripts (actions) distributed to the general public. For scripts used internally by yourself or within your organization, alerts remain a valuable option. After all, a well-placed Cancel button can save you from having to undo!

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