Action Forms

Omni Automation enables the creation of powerful automation tools for addressing the tasks and challenges involved in the creative use of productivity applications like OmniGraffle and OmniOutliner.

Action Forms enable the display, by an Omni Automation script plugin (action), of standard form selection and input elements, such as text fields, menus, and checkboxes (switches on iOS), so that they may provide the user with the choices and data to be used by script in its processing.

In addition, Form Elements may include optional labels and be assigned default values and ordering, so as to create Form Dialogs that present data and choices in an easy-to-understand and organized manner. And, Form Dialogs can be enhanced with customized prompts and approval button titles.

form-example-with-callouts

A macOS form dialog sheet

The following documentation details the use of the Form and Form.Field classes, along with their corresponding functions and methods, demonstrating how to create, display, and respond to Action Forms included in your action plugins.

This overview will begin with an examination of the Form class and how to create a new form object in a script.

The Form Class

The Form class provides a mechanism to collect input from the user. Each form contains one or more instances of the Field subclasses (form elements), to which each are assigned a unique key. As the form is filled out by the user, the form’s default Values object is populated with the values of the form elements in the form dialog.

Instances of the Form class are created using the standard JavaScript new object constructor:

var inputForm = new Form()

The result is an empty instance of the Form class, ready to contain various elements of the Form.Field class, such as text input fields, date pickers, checkboxes, and popup menus.

Form Elements

A Form is a container that contains various form elements, such as popup menus, checkboxes, and date and text input fields. All of the form elements are instances of the Form.Field class, and they share the following properties:

Instances of the Form.Field class are created using the standard JavaScript new object constructor including the parameters specific to each type of element:

For example, here is script code that creates each of the various types of form elements:

textInput = new Form.Field.String("name", "Name", null) dateInput = new Form.Field.Date("date", "Date", null) popupMenu = new Form.Field.Option( "menu", "Position", [1,2,3], ["Top", "Middle", "Bottom"], 1 ) checkbox = new Form.Field.Checkbox("checkbox", "Append", false)

Adding|Removing Elements to|from a Form

Created Form Elements are added to an existing Form instance using the addField(…) instance function of the Form class.

For example, here is how the previously created form elements would be added to the previously created form:

NOTE: if a position index is not included as a parameter in the addField(…) function, the created element is added to the end of the set of current form elements. Also, if the position index parameter is not used, then form elements are added to the current set of form elements in the order in which the function is called to add them. The topmost position index is 0.

Displaying the Form

Once a form has been populated with elements, it is displayed within the application by using the show(…) instance function of the Form class:

The show(…) function takes two text string for its parameters: the dialog title/prompt, and optionally, the title of the approval button.

NOTE: The JavaScript Promise object represents the eventual completion (or failure) of an asynchronous operation, and its resulting value. It is discussed in more detail in the next section about validating, retrieving, and using the form data.

Here is an example script that will display a form containing each of the form element types:

inputForm = new Form() textInput = new Form.Field.String("name", "Name", null) dateInput = new Form.Field.Date("date", "Date", null) popupMenu = new Form.Field.Option( "menu", "Position", [1,2,3], ["Top", "Middle", "Bottom"], 1 ) checkbox = new Form.Field.Checkbox("checkbox", "Append", false) inputForm.addField(textInput, 0) inputForm.addField(dateInput, 1) inputForm.addField(popupMenu, 2) inputForm.addField(checkbox, 3) formPrompt = "This is the form prompt" buttonTitle = "OK" inputForm.show(formPrompt, buttonTitle)
omnigraffle://localhost/omnijs-run?script=try%7BinputForm%20%3D%20new%20Form%28%29%0AtextInput%20%3D%20new%20Form%2EField%2EString%28%22name%22%2C%20%22Name%22%2C%20null%29%0AdateInput%20%3D%20new%20Form%2EField%2EDate%28%22date%22%2C%20%22Date%22%2C%20null%29%0ApopupMenu%20%3D%20new%20Form%2EField%2EOption%28%22menu%22%2C%20%22Position%22%2C%20%5B1%2C2%2C3%5D%2C%20%5B%22Top%22%2C%20%22Middle%22%2C%20%22Bottom%22%5D%2C%201%29%0Acheckbox%20%3D%20new%20Form%2EField%2ECheckbox%28%22checkbox%22%2C%20%22Append%22%2C%20false%29%0AinputForm%2EaddField%28textInput%29%0AinputForm%2EaddField%28dateInput%29%0AinputForm%2EaddField%28popupMenu%29%0AinputForm%2EaddField%28checkbox%29%0AformPrompt%20%3D%20%22This%20is%20the%20form%20prompt%22%0AbuttonTitle%20%3D%20%22OK%22%0AinputForm%2Eshow%28formPrompt%2C%20buttonTitle%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

A form displayed in a sheet overlay in OmniGraffle on macOS:

example-form-display

A form displayed in a dialog overlay in OmniGraffle on iOS:

form-example-ios

The next sections will examine how to integrate forms into actions, and how to validate and retrieve the data from a displayed form.

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