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


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.1", "description": "This action will display an alert showing the metadata of this action.", "label": "Show Plug-In Info", "shortLabel": "Plug-In Info", "paletteLabel": "Plug-In Info", "image": "info.square.fill" }*/ (() => { const action = new PlugIn.Action(function(selection, sender){ desc = action.description auth = action.plugIn.author filename = action.name id = action.plugIn.identifier label = action.label 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){ 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.