Plug-Ins

An outstanding feature of Omni Automation is its mechanism for integrating scripts with applications through the use of user-created and deployed plug-ins. An Omni Automation plug-in is a single-file script or script bundle that exposes script functionality contextually through the host Omni application’s “Automation” and “Share” menus. With a little bit of effort, you can create, deploy, and share your own plug-ins to add-to and automate the abilities of OmniFocus and the other Omni applications.

As an example, in this section you’ll learn how to create and install a plug-in that removes tags from all of the selected tasks selected in OmniFocus.

Editor Application

While the built-in automation console in OmniFocus is useful for writing and testing short script snippets, it is not designed to replace a full-featured editor application. To write Omni Automation plug-ins, you’ll need to use a text editor app or one of the 3rd-party JavaScript editor applications found on the iPad App Store or the Mac App Store.

For the purposes of documentation, this section will contain illustrations that feature the use of the Textastic Code Editor application from Alexander Blach.

(For those following this tutorial on a macOS device, a link to open the plug-in template in the BBEdit application is provided as well)

The Plug-In Template

Omni Automation plug-ins are divided into two sections: the plug-in metadata properties record (lines 1-12 below), and the plug-in function code (lines 13-27 beow).

Basic Plug-In Template
Copy Open in Textastic Open in BBEdit

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Action Author",
	"identifier": "com.youOrCompany.of.actionName",
	"version": "1.0",
	"description": "Action Description",
	"label": "Menu Item Title",
	"shortLabel": "Toolbar Item Title",
	"paletteLabel": "Toolbar Item Title",
	"image": "gearshape.fill"
}*/
(() => {
	const action = new PlugIn.Action(function(selection, sender){
		// action code
		// selection options: tasks, projects, folders, tags, allObjects, databaseObjects
		// PUT YOUR PROCESSING CODE HERE
	});

	action.validate = function(selection, sender){
		// validation code
		// selection options: tasks, projects, folders, tags, allObjects, databaseObjects
		// PUT YOUR VALIDATION CODE HERE
	};
	
	return action;
})();

(see below) The plug-in template opened in the Textastic application:

Next, we’ll edit the plug-in’s metadata record.

The Plug-In Metadata Properties

A plug-in’s metadata properties define how a plug-in is integrated by the host Omni application. Here is an explanation of each metadata property:

Plug-In Metadata
Copy

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Action Author",
	"identifier": "com.youOrCompany.of.actionName",
	"version": "1.0",
	"description": "Action Description",
	"label": "Menu Item Title",
	"shortLabel": "Toolbar Item Title",
	"paletteLabel": "Toolbar Item Title",
	"image": "gearshape.fill"
}*/

The Plug-In Validation Function

Optionally, plug-ins can be designed to be only be available when specific conditions exist within the application or the app’s selected objects.

For example, our example plug-in for clearing tags from selected tasks should only be enabled in the Automation or Sharing menus when one or more tasks are selected in the application interface.

Your code for performing the conditional checks is placed within the validation function in the template (lines 18-22 in the template)

Validation Function

action.validate = function(selection, sender){
	// validation code
	// selection options: tasks, projects, folders, tags, allObjects, databaseObjects
	// PUT YOUR VALIDATION CODE HERE
};

To assist you in validating the plug-in, two items are automatically passed into the function:

• The selection object that has a value that is an array of items currently selected in the application interface: tasks, projects, folders, tags, or a collection of selected database objects (folders, projects, and tasks)

• The sender object that has a value indicating the mechanism used to trigger the execution of the plug-in. (Menu Item, Toolbar Button, or null if a remote script)

Since a validation function must return a boolean value (true or false) we can use the passed-in selection object to determine if one or more tasks are selected in OmniFocus, and return the appropriate boolean value.

If the validation function returns a value of false, the plug-in’s menu item will be disabled in the Automation Menu and will not appear on the Sharing Menu.

To determine whether one or more tasks are currently selected, we return the value of a script statement that counts the number of tasks returned by the tasks property of the selection object and compares it to zero (none):

The Validation Statement (true|false)
Copy

return (selection.tasks.length > 0)

If one or more tasks are selected in the application interface, this statement will return a value of true, otherwise it will return a value of false.

The Plug-In Action Function

The plug-in action function performs the work of the plug-in, which in the case of this example plug-in is clearing all tags from the tasks selected in the application interface.

The Action Function

const action = new PlugIn.Action(function(selection, sender){
	// action code
	// selection options: tasks, projects, folders, tags, allObjects, databaseObjects
	// PUT YOUR PROCESSING CODE HERE
});

As with the validation function, the action function also receives the selection and sender objects as input to the function. (line 01 above)

The value of the selection object is an array of object references to the selected tasks. The script for processing each of the selected tasks uses the JavaScript forEach(…) function to iterate the list of tasks, applying the clearTags() function of the Task class to each selected task:

Clear Tags from Selected Tasks
Copy

selection.tasks.forEach(task => task.clearTags())

With your edits saved, the completed plug-in code should look similar to the example shown above.

Installing the Plug-In

Now that the plug-in has been created and edited, you’re ready to install the plug-in in OmniFocus.

(above) Selecting the OmniFocus icon in the Share dialog will trigger the plug-in installation process in OmniFocus, which will display the installation security dialog shown below (left):

Using the Plug-In

Now that the plug-in is installed, let’s use it to remove the tags from the previously created task: “Staff Meeting”

All assigned tags will be cleared from the selected tasks.

Managing Plug-Ins

All of the Omni applications offer extensive control of installed plug-ins. Let’s examine the basics of plug-in management.

The Configure Plug-Ins sheet will be displayed:

More OmniFocus Plug-In Templates

This website hosts online Template Generator forms for generating Omni Automation plug-ins for each of the Omni apps, including the Template Generator for OmniFocus that contains many preset plug-in templates for you to use.

Summary

In this section you learned:

• How to create, install, and run an Omni Automation plug-in for OmniFocus.

• How to access the built-in plug-in management tools.

In the next next section we’ll finish up and restore the Inbox.