Plug-In Forms: Text & Password Input

The Form.Field.String class provides a fundamental mechanism for prompting for and retrieving textual data from a script user, is the use of the text input field. Omni Automation action forms provide this form element to enable the passing of textual data to the script for processing.

Constructor

• new Form.Field.String(key: String, displayName: String or null, value: Object or null, formatter: Formatter or null) → (Form.Field.String) • Returns a new String field, optionally with an initial value and formatter. If a formatter is specified, the value should be of the output type from the formatter or null. If no formatter is specified, the value should be a string or null.

Text Input Field
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

textInputField = new Form.Field.String(
	"textInputField",
	"Label",
	null,
	null
)

The resulting value of the text input field will be the text string entered by the user during the execution of the form containing the field.

Using a Formatter

By default, the Form.Field.String is designed to work with instance of the String class as both its input and returned value (output). Optionally, you may use an instance of the Formatter class (LINK) to both display and provide entered content in other related formats such as in the decimal formatted currency values shown in the following example.

(⬇ see below ) Although the user enters a numeric value in the field, it is displayed as a formatted currency value, in this case Swedish Kroner:

(⬇ see below ) When the form is executed, the resulting value will be an instance of the Decimal class since the formatter used is an instance of the Formatter.Decimal class. The previously created formatter instance can then be used again should the data need to be displayed after processing. In shown example, the result value is displayed as both decimal and formatted string:

Formatting Input and Output
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

code = new Locale("sv_SE").currencyCode
fmtr = Formatter.Decimal.currency(code)
defaultValue = fmtr.decimalFromString('1000')
inputForm = new Form()
amountImput = new Form.Field.String(
	"amount",
	"User",
	defaultValue,
	fmtr
)
formPrompt = "Enter the amount in Swedish Kroner:"
buttonTitle = "Continue"
inputForm.addField(amountImput)
formPromise = inputForm.show(formPrompt, buttonTitle)
formPromise.then(function(formObject){
	decimalValue = formObject.values["amount"]
	displayString = fmtr.stringFromDecimal(decimalValue)
	alertMessage = "Amount: " + decimalValue.toString() + "\n" + "Kroner: " + displayString
	new Alert("Swedish Kroner", alertMessage).show()
})

 1  Currency Code • An instance of the Locale class is created for Sweden and the currency code for that locale is stored in a variable.

 2  Decimal Formatter • An instance of the Formatter.Decimal class is created with the value of its currency property set to use the previous code.

 3  Default Value • Since the formatter will be applied to the field, its provided value must be an instance of the Decimal class. The decimalFromString() instance function of the Formatter.Decimal class is used to convert the numeric string into a decimal object.

 4  New Form • A new instance of the Form class is created and stored.

 5-10  New Text Field • A new instance of the Form.Field.Text class is instantiated using the previously created decimal formatter instance and default value.

 11-14  Show Form • The field is added to the form, which is then shown to the user.

 15-20  Process Form Results • Process the form results, which is a form values object.

 17  Apple Formatter • Since the resulting value is a decimal, use the existing formatter instance to format the decimal for display.

 18-19  Display Alert • Show the results to the user.

Setting iOS Keyboard for Input

On iOS systems only (iPhone), there is an optional property of the Form.Field.String class for setting which keyboard is displayed on the device (iPhone | iPod Touch):

• keyboardType (KeyboardType) • A specific KeyboardType may be assigned to better match the input needed for a given field. Changing this value after the containing Form is shown will have no effect.

Class properties of the KeyboardType class:

• ASCIICapable (KeyboardType r/o) • Displays a keyboard which can enter ASCII characters

• ASCIICapableNumberPad (KeyboardType r/o) • A number pad (0–9) that will always be ASCII digits.

• DecimalPad (KeyboardType r/o) • A number pad with a decimal point.

• Default (KeyboardType r/o) • Default type for the current input method.

• EmailAddress (KeyboardType r/o) • A type optimized for multiple email address entry (shows space @ . prominently).

• NamePhonePad (KeyboardType r/o) • A type optimized for entering a person’s name or phone number.

• NumberPad (KeyboardType r/o) • A number pad with locale-appropriate digits (0–9, ۰-۹, ०-९, etc.). Suitable for PIN entry.

• NumbersAndPunctuation (KeyboardType r/o) • Numbers and assorted punctuation.

• PhonePad (KeyboardType r/o) • A phone pad (1–9, *, 0, #, with letters under the numbers).

• Twitter (KeyboardType r/o) • A type optimized for twitter text entry (easy access to @ #)

• URL (KeyboardType r/o) • A type optimized for URL entry (shows . / .com prominently).

• WebSearch (KeyboardType r/o) • A default keyboard type with URL-oriented addition (shows space . prominently).

• all (KeyboardType r/o) • An array of all items of this enumeration. Used in the creation of forms.

Scripts can use the shared Device class (LINK) to determine the type of Apple device hosting the Omni app and plug-in.

Assigning Keyboard Type for Field
Copy

textInputField = new Form.Field.String(
	"callNumber",
	"[0 to 9, +, *, #]",
	null
)
if (Device.current.type === DeviceType.iPhone){
	textInputField.keyboardType = KeyboardType.PhonePad
}

The previous example is from the Add Call Task plug-in for OmniFocus.

Set Capitalization for Text Input Field
Copy

textInputfield.autocapitalizationType = TextAutocapitalizationType.AllCharacters

• AllCharacters (TextAutocapitalizationType) • Capitalize all characters.

• None (TextAutocapitalizationType) • Turn off autocapitalization.

• Sentences (TextAutocapitalizationType) • Perform autocapitalization at the beginning of sentences.

• Words (TextAutocapitalizationType) • Perform autocapitalization on he beginning of words.

• all (Array of TextAutocapitalizationType) • Used in the creation of form elements.

Text Input Example
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

textInputField = new Form.Field.String(
	"textInput",
	"ID",
	"PCODE-XXXX-MM.DD.YYYY"
)
inputForm = new Form()
inputForm.addField(textInputField)
inputForm.show("Please enter the project identifier:","Continue")
.then(
	function(formObject){
		console.log(formObject.values['textInput'])
	}
)

Example: Integer Input

The following code includes the display, validation, and processing of a form containing a single text input field. In this example, the field is designed to accept only integers occurring within a specified range.

Integer Input Example
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

// CONSTRUCT THE FORM
inputForm = new Form()

// CREATE FORM ELEMENTS: TEXT INPUT, DATE INPUT, AND CHECKBOX
textField = new Form.Field.String("input", "(1 to 34)", null)

// ADD THE ELEMENTS TO THE FORM
inputForm.addField(textField)

// DIALOG PROMPT AND OK BUTTON TITLE
formPrompt = "Enter the number of segments to add:"
buttonTitle = "Continue"

// DISPLAY THE FORM DIALOG
formPromise = inputForm.show(formPrompt, buttonTitle)

// VALIDATE FORM CONTENT
inputForm.validate = function(formObject){
	// EXTRACT VALUES FROM THE FORM’S VALUES OBJECT
	var textValue = formObject.values['input']

	if(!textValue){return false}
				
	intValue = parseInt(textValue)
				
	validation = (isNaN(intValue) || intValue > 34 || intValue < 1) ? false:true
				
	// RETURN THE VALIDATION STATUS
	return validation
}

// PERFORM PROCESSES USING FORM DATA
formPromise.then(function(formObject){
	textValue = formObject.values['input']
	intValue = parseInt(textValue)
	console.log(intValue)

	// PROCESSING STATEMENTS GO HERE
})

Text Input Validations

More examples of text input validations, such as entering a valid email address, are documented on the Form Examples page.

Password Input (Form.Field.Password)

As part of the shared URL class, Omni Automation supports the fetch() function in use with HTTP Request/Response API. In plug-ins that implement a form text field meant for the input of passwords or other secure strings, the Form.Field.Password class provides a mechanism for users to enter data that will appear as a string of bullet characters.

The Form.Field.Password class is similar to the Form.Field.String class but lacks the formatting option:

Constructor

• new Form.Field.Password(key: String, displayName: String or null, value: String or null) → (Form.Field.Password) • Returns a new Password field, optionally with an initial value. The displayed text will be obscured.

Password Input Field
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

inputForm = new Form()
accountInput = new Form.Field.String(
	"account",
	"User",
	null,
	null
)
if(Device.current.type !== DeviceType.mac){accountInput.autocapitalizationType = TextAutocapitalizationType.None}
passwordInput = new Form.Field.Password(
	"password",
	"Password",
	null
)
formPrompt = "Enter your credentials:"
buttonTitle = "Continue"
inputForm.addField(accountInput)
inputForm.addField(passwordInput)
inputForm.show(formPrompt, buttonTitle)