Plug-Ins: Calling Plug-Ins Externally

“Actions” are the functions that perform the work of a plug-in. Bundle plug-ins may have one or more actions, while single-file plug-ins usually have a single action. Plug-In actions are available to be called by other actions and external Omni Automation scripts.

To access information from a plug-in, the identifier of the target plug-in is required.

TIP: To get a list of the identifiers of all plug-ins installed in an Omni application, run the following statement that uses the PlugIn class:

Get Identifiers of Installed Plug-Ins
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

var pluginIDs = PlugIn.all.map(plugin => plugin.identifier)
console.log(pluginIDs.join("\n"))
//--> ["com.omni-automation.of.sender-example", "com.omni-automation.info-for-selected-item", "com.omni-automation.all.show-plug-in-info"]

Here’s a script for getting a list of the names of the actions contained by a plug-in specified by its identifier:

Get Action Names from Specified Plug-In
Copy

var pluginID = "com.omni-automation.all.show-plug-in-info"
var plugin = PlugIn.find(pluginID)
if (plugin == null){
	throw new Error("Plug-in not installed.")
} else {
	var actionNames = plugin.actions.map(action => action.name)
	console.log(actionNames)
	//--> ["all-show-plug-in-info"]
}

Validating an Action

Plug-in actions may have a validation function that determines whether or not the action is enabled in the plug-in menu. If an action does not have a validation function, the result of validating the action is always true. Validation is often based upon conditions in the document, such as whether there are selected graphics.

Omni Automation scripts can call an action’s validation handler to determine the status of the action. The following example function will return a value of true or false indicating the status of the action.

Validate Action Function
Copy

function validatePlugInAction(pluginID, actionName){
	var plugin = PlugIn.find(pluginID)
	if (plugin == null){throw new Error("Plug-in not installed.")}
	var actionNames = plugin.actions.map(action => action.name)
	if(actionNames.indexOf(actionName) === -1){
		throw new Error(`Action “${actionName}” is not in the plug-in.`)
	} else {
		return plugin.action(actionName).validate()
	}
}
validatePlugInAction("com.omni-automation.all.show-plug-in-info", "all-show-plug-in-info")

Executing an Action

Omni Automation scripts can run a plug-in’s actions by calling the perform() method on an action instance.

Here is a function for executing a plug-in action specified using the plug-in identifier and the action name:

Execute Plug-In Action
Copy

function performPlugInAction(pluginID, actionName){
	var plugin = PlugIn.find(pluginID)
	if (plugin === null){throw new Error("Plug-in not installed.")}
	var actionNames = plugin.actions.map(action => action.name)
	if(actionNames.indexOf(actionName) === -1){
		throw new Error(`Action “${actionName}” is not in the plug-in.`)
	} else {
		if(plugin.action(actionName).validate()){
			plugin.action(actionName).perform()
		} else {
			throw new Error(`The action “${actionName}” is not validated to execute.`)
		}
	}
}
performPlugInAction("com.omni-automation.all.show-plug-in-info", "all-show-plug-in-info")

Adapting a Plug-In for Remote Execution

Actions called by remote scripts will have selection objects that are undefined. To adapt actions to be “callable” by remote scripts, check for the type of the selection object and if it is undefined, add a script statement for getting the current document selection.

In the following example action for OmniOutliner, a list of selected items (rows) is generated if the plug-in is called externally:

Adapting Action for External Calling
Copy

((){
	const action = new PlugIn.Action(function(selection, sender){
		// If called externally (from script) generate selection array
		if (typeof selection === 'undefined'){
			// convert nodes into items
			let nodes = document.editors[0].selectedNodes
			let selectedItems = nodes.map((node) => {return node.object})
		} else {
			let selectedItems = selection.items
		}
		// action code goes here…
	});

	action.validate = function(selection){
		// Validation check. For example, are items selected?
		// if called externally (from script) generate selection array
		if (typeof selection == 'undefined'){
			let selNodesCount = document.editors[0].selectedNodes.length
			return (selNodesCount > 0)
		} else {
			return (selection.items.length > 0)
		}
	};

	return action;
})();