×

Preferences

The ability for plug-ins to store, retrieve, and share data is an essential element for creating versatile automation tools. The Preferences class enables plug-ins to fully retain and utilize data for optimum workflow design and function.

NOTE:

Constructors

Instance Properties

Instance Functions

Example Plug-In: Counter

The following example plug-in displays a counter showing the number of times the alert has been displayed.

preferences-counter-alert

To reset the counter, hold down the Control key when selecting the plug-in from the Automation menu.

Incrementing Alert
 

/*{ "type": "action", "targets": ["omnifocus","omniplan","omnigraffle","omnioutliner"], "author": "Otto Automator", "identifier": "com.omni-automation.all.preferences-counter", "version": "1.0", "description": "Demonstrates the use of the Preferences class to store and retrieve data.", "label": "Preferences Counter Example", "shortLabel": "Preferences Counter Example" }*/ (() => { // DECLARE PREFERENCES INSTANCE let preferences = new Preferences() // NO ID = PLUG-IN ID console.log(preferences.identifier) var action = new PlugIn.Action(function(selection, sender){ // action code let incrementedCount = 0 console.log("app.controlKeyDown", app.controlKeyDown) if (app.controlKeyDown){ console.log("Show Alert") let alertMessage = "Reset the stored value?" let alert = new Alert("Confirmation Required", alertMessage) alert.addOption("Reset") alert.addOption("Cancel") alert.show(buttonIndex => { if (buttonIndex === 0){ preferences.write("incrementedCount", 0) } }) } else { let incrementedCount = preferences.readNumber("incrementedCount") console.log("incrementedCount-stored", incrementedCount) let newIncrementedCount = incrementedCount + 1 preferences.write("incrementedCount", newIncrementedCount) let alertTitle = "Incrementing Alert" let alertMessage = "This alert has been shown " + String(newIncrementedCount) + " times." let alert = new Alert(alertTitle, alertMessage).show() } }); action.validate = function(selection, sender){ // validation code return true }; return action; })();

 

Example Plug-In: Form Data

A standard use of the Preferences class is to store the chosen values of forms so that the forms will return to their former state when displayed again. The following plug-in displays a form containing a menu, text field, date input, and checkbox. The Preferences class is used to store and retrieve the values set by the user.

preferences-class-dialog

To reset the values to their defaults, hold down the Control key when selecting the plug-in from the Automation menu.

Preferences Form Example
 

/*{ "type": "action", "targets": ["omnifocus","omniplan","omnigraffle","omnioutliner"], "author": "Otto Automator", "identifier": "com.omni-automation.all.preferences-example", "version": "1.0", "description": "Demonstrates the use of the Preferences class to store and retrieve data.", "label": "Preferences Example", "shortLabel": "Preferences Example" }*/ (() => { // DECLARE PREFERENCES INSTANCE let preferences = new Preferences() // NO ID = PLUG-IN ID console.log(preferences.identifier) var action = new PlugIn.Action(function(selection, sender){ // action code console.log("app.controlKeyDown", app.controlKeyDown) if (app.controlKeyDown){ console.log("Show Alert") let alertMessage = "Remove the stored values?" let alert = new Alert("Confirmation Required", alertMessage) alert.addOption("Remove") alert.addOption("Cancel") alert.show(buttonIndex => { if (buttonIndex === 0){ preferences.remove("optionsMenu") preferences.remove("textInput") preferences.remove("checkboxSwitch") preferences.remove("dateInput") } }) } else { // DEFAULTS let defaultMenuIndex = 0 let defaultNameValue = "" let defaultBooleanValue = false let defaultdateValue = new Date() // READ STORED VALUES IF ANY. SET DEFAULTS IF NEEDED. let menuIndex = preferences.readNumber("optionsMenu") console.log("menuIndex-stored", menuIndex) if(!menuIndex){ menuIndex = defaultMenuIndex } let nameValue = preferences.readString("textInput") console.log("nameValue-stored", nameValue) if(!nameValue){ nameValue = defaultNameValue } let booleanValue = preferences.readBoolean("checkboxSwitch") console.log("booleanValue-stored", booleanValue) if(!booleanValue){ booleanValue = defaultBooleanValue } let dateValue = preferences.readDate("dateInput") console.log("dateValue-stored", dateValue) if(!dateValue){ dateValue = defaultdateValue } let menuItems = ["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"] let menuIndexes = [0,1,2,3,4,5,6] let optionsMenu = new Form.Field.Option( "optionsMenu", "Weekday", menuIndexes, menuItems, menuIndex ) let textInputField = new Form.Field.String( "textInput", "Name", nameValue ) let checkSwitchField = new Form.Field.Checkbox( "checkboxSwitch", "I accept the standard terms and conditions", booleanValue ) let dateInputField = new Form.Field.Date( "dateInput", "Date", dateValue ) let inputForm = new Form() inputForm.addField(optionsMenu) inputForm.addField(textInputField) inputForm.addField(checkSwitchField) inputForm.addField(dateInputField) let formPrompt = "Make selections and enter values:" let buttonTitle = "Continue" let formPromise = inputForm.show(formPrompt, buttonTitle) inputForm.validate = function(formObject){ return true } formPromise.then(function(formObject){ menuIndex = formObject.values['optionsMenu'] console.log('menuIndex-write', menuIndex) nameValue = formObject.values['textInput'] if(!nameValue){nameValue = ""} // convert null to empty string console.log('nameValue-write', nameValue) booleanValue = formObject.values['checkboxSwitch'] console.log('booleanValue-write', booleanValue) dateValue = formObject.values['dateInput'] console.log('dateValue-write', dateValue) // STORE THE VALUES preferences.write("optionsMenu", menuIndex) preferences.write("textInput", nameValue) preferences.write("checkboxSwitch", booleanValue) preferences.write("dateInput", dateValue) }) } }); action.validate = function(selection, sender){ // validation code return true }; return action; })();

1st-Run Interaction Plug-In

A plug-in that uses the Preferences class to create a 1st-run interaction. To reset the plug-in, hold down Control modifier key when selecting plug-in from the Automation menu.

1st-Run Sensor


/*{ "type": "action", "targets": ["omnifocus"], "author": "Otto Automator", "identifier": "com.omni-automation.all.first-run-sensor", "version": "1.0", "description": "This plug-in will present an alert the first time it is executed. To reset the plug-in, hold down Control key when selecting from Automation menu.", "label": "First Run Example", "shortLabel": "First Run Example" }*/ (() => { let preferences = new Preferences() const action = new PlugIn.Action(function(selection, sender){ (async () => { let incrementedCount = preferences.readNumber("incrementedCount") if(!incrementedCount){ preferences.write("incrementedCount", 0) incrementedCount = 0 } if (app.controlKeyDown){ let alertMessage = "Reset the stored count?" let alert = new Alert("Confirmation Required", alertMessage) alert.addOption("Reset") alert.addOption("Cancel") let buttonIndex = await alert.show() if (buttonIndex === 0){ preferences.write("incrementedCount", 0) console.log("incrementedCount", "reset") return "user reset" } } console.log("incrementedCount", incrementedCount) if (incrementedCount === 0){ let alertTitle = "Plug-In 1st Run" let alertMessage = "Welcome to the 1st-Run Plug-In!" await new Alert(alertTitle, alertMessage).show() } preferences.write("incrementedCount", incrementedCount + 1) // PROCESSING CODE GOES HERE })().catch(err => console.error(err.message)) }); action.validate = function(selection, sender){ // validation code return true }; return action; })();