Plug-In API (PlugIn Class)

The following are the definitions and descriptions for the PlugIn class its related functions, properties, and elements.

IMPORTANT: When referencing an Omni Automation plug-in file or bundle, the term “plug-in” is hyphenated. However, when referencing the PlugIn class, no hypens or spaces are used, and the combined words “Plug” and “In” each begin with a capitalized character.

PlugIn Class Functions

Find Installed Plug-In



var plgn = PlugIn.find("com.omni-automation.og.sort-selected-shapes")
if(!plgn){new Alert("ITEM NOT FOUND", "Plug-In not installed.").show()}

PlugIn Class Properties

PlugIn.all.forEach((plugin, index) => { if (index != 0){console.log(" ")} console.log("FILENAME:", plugin.displayName) console.log("ID:", plugin.identifier) console.log("VERSION:", plugin.version.versionString) console.log("AUTHOR:", plugin.author) console.log("DESC:", plugin.description) console.log("URL:", plugin.URL.string) })
Log Properties of Installed Plug-Ins

  



PlugIn.all.forEach((plugin, index) => {
	if (index != 0){console.log(" ")}
	console.log("FILENAME:", plugin.displayName)
	console.log("ID:", plugin.identifier)
	console.log("VERSION:", plugin.version.versionString)
	console.log("AUTHOR:", plugin.author)
	console.log("DESC:", plugin.description)
	console.log("URL:", plugin.URL.string)
})
log-plugin-properties

PlugIn Instance Properties

PlugIn Instance Functions

A set of functions usually used with bundle plug-ins:

Here’s an example of importing a plug-in resource to an OmniGraffle canvas:

Importing Resource to Canvas



var plugin = PlugIn.find("com.YourCompany.og.PlugInName")
var imageFileName = "ImageName.png"
var url = plugin.resourceNamed(imageFileName)
url.fetch(data => {
	var aRect = new Rect(0, 0, 72, 72)
	var cnvs = document.windows[0].selection.canvas
	var aGraphic = cnvs.addShape('Rectangle', aRect)
	aGraphic.strokeThickness = 0
	aGraphic.shadowColor = null
	aGraphic.fillColor = null
	aGraphic.image = addImage(data)
	aGraphic.name = imageFileName
	var imageSize = aGraphic.image.originalSize
	var imgX = imageSize.width
	var imgY = imageSize.height
	aGraphic.geometry = new Rect(aGraphic.geometry.x, aGraphic.geometry.y, imgX, imgY)
	document.windows[0].selection.view.select([aGraphic])
})

PlugIn.Action Class

“Actions” are the script functions that perform the work of their parent plug-in. Single-file plug-ins contain a single action function, while bundle plug-ins may contain one or more actions.

Constructor

Instance Properties

Example

The following plug-in can be installed with all Omni applications, and uses both the PlugIn class properties and the PlugIn.Action properties to display an alert containing the metadata information for the host plug-in:

plug-in-action-info-alert 
Show Plug-In Info
 


/*{
	"type": "action",
	"targets": ["omnifocus","omnigraffle","omniplan","omnioutliner"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.all.show-plug-in-info",
	"version": "1.0",
	"description": "This action will display an alert showing the metadata of this action.",
	"label": "Show Plug-In Info",
	"shortLabel": "Plug-In Info"
}*/
(() => {
	const action = new PlugIn.Action(function(selection, sender){
		// action code
		let desc = action.description
		let auth = action.plugIn.author
		let filename = action.name
		let id = action.plugIn.identifier
		let label = action.label
		let message = "LABEL: " + label
		message += "\n" + "FILENAME: " + filename
		message += "\n" + "AUTHOR: " + auth
		message += "\n" + "DESCRIPTION: " + desc
		message += "\n" + "ID: " + id
		new Alert("Plug-In Info", message).show()
	});

	action.validate = function(selection, sender){
		// validation code
		return true
	};
	
	return action;
})();

NOTE: See the Single-File Plug-In and Bundle Plug-In sections for more information about plug-ins and actions.

PlugIn.Handler Class

“Handlers” are functions that get triggered automatically when specifically-enabled “events” happen in the host application.

Constructor

Instance Properties

NOTE: See the Handlers Section for more information.

PlugIn.Library Class

Omni Automation Libraries are specialized plug-ins that provide the means for storing, using, and sharing Omni Automation functions. They make automation tasks easier by dramatically shortening scripts, and they enable the ability to share useful routines with other devices.

Constructor

Instance Properties

Here is the basic template for a single-file library plug-in:

Basic Single-File Library



/*{
	"type": "library",
	"targets": ["omnigraffle","omnioutliner","omnigraffle","omniplan"],
	"identifier": "com.omni-automation.all.libraryName",
	"version": "1.0"
}*/
(() => {
	var myLibrary = new PlugIn.Library(new Version("1.0"));
  
		myLibrary.myFirstFunction = function(passedParameter){
			// function code
			return myFirstFunctionResult
		};
		
		myLibrary.mySecondFunction = function(passedParameter){
			// function code
			return mySecondFunctionResult
		};

	return myLibrary;
})();

Here’s example script statements calling functions within a library:

Calling a Library



// locate the library’s parent plug-in by identifier
var plugin = PlugIn.find("com.YourIdentifier.NameOfPlugIn")
if (plugin == null){throw new Error("Library plug-in not installed.")}
// load a library identified by name
var firstLibrary = plugin.library("NameOfFirstLibrary")
// load a library identified by name
var secondLibrary = plugin.library("NameOfSecondLibrary")
// call a library function by name
var callResult = firstLibrary.nameOfLibraryFunction()
// call a library function by name
secondLibrary.nameOfLibraryFunction(callResult)

NOTE: See the Library Section for more information.