Omni Automation Plug-Ins

Omni Automation Plug-Ins are a great way to deliver organized contextual automation tools for Omni applications in both macOS and iOS. Easily user-installed, an Omni Automation Plug-In may contain two types of automation resources:

Example Plug-In for OmniGraffle

“Sal’s Snippets for OmniGraffle” an example Plug-In containing actions and libraries, can downloaded here. Current version is: 5.9

The video below shows how to install the example Plug-In on iOS, and how to access the functions of the Plug-In:

The Plug-In Bundle

Omni Automation Plug-In files are “bundles,” which are essentially folders with a special file extension appended to their their name (For example, the filename for Plug-Ins for the OmniGraffle application end with “omnigrafflejs”). Within a Plug-In bundle are the files and directories that define the manner in which the Plug-In provides its functionality. This section will examine the various Plug-In components in detail.

To assist you in understanding and creating your own Plug-Ins, you can download a simplified OmniGraffle Plug-In template here and an OmniOutliner Plug-In template here. To open the unarchived Plug-In bundle on macOS, right-click the file and choose “Show Package Contents” from the Finder’s contextual menu.

The illustration below shows the hierarchy and contents of an Omni Automation Plug-In bundle:

plugin-anatomy

At the topmost level in the bundle folder are two items:

The Manifest

The Plug-In manifest JSON text file contains between 5 to 7 keys and their corresponding values. The first key defaultLocale is used to indicate the default language used to render the Plug-In’s menu items. The second key identifier is a text string (without spaces) representing your company or development identity. These identifiers usually follow the format shown in the example. Of course the key author is the name of the person or company who created the Plug-In, and the description key is a short explanation of the Plug-In’s automation features. The value of the version key is a numeric string in standard version format: 1.x or 1.x.x

{ "defaultLocale":"en", "identifier": "com.YourIdentifier.NameOfApp", "author": "Your Name or Organization", "description": "A collection of actions (scripts) for NameOfApp.", "version": "1.0", "actions": [ { "identifier": "myFirstActionFileName", "image": "1st-action-toolbar-icon.png" }, { "identifier": "mySecondActionFileName", "image": "2nd-action-toolbar-icon.png" } ], "libraries": [ { "identifier": "MyFirstLibraryFileName" }, { "identifier": "MySecondLibraryFileName" } ] }

The value of the actions key is an array of key:value pairs for identifying the actions (scripts) provided by the Plug-In. Each action entry contains two key:value pairs: the identifier key has a value that is the file name of the JavaScript corresponding action file without its file extension of “.js”. The image key has a value that is the name of the image file (with file extension) that is the toolbar icon for the action.

The value of the libraries key is an array of key:value pairs for identifying any libraries provided by the Plug-In. Each library entry contains a single key:value pairs: the value of the identifier key is the file name of the JavaScript corresponding library file without its file extension of “.js”.

The Manifest Strings file

The mainfest.strings file, located in the localized project folder within the Resources folder, is a text file containing a single key:value pair indicating the Plug-In name that should be displayed to the user in any menus. The key of the manifest.strings file is the value of the Plug-In identifier key from the manifest.json file. The value of the key is the localized string for the Plug-In name.

The Resources folder

The Resources folder contains all other Plug-In components, including:

plugin-anatomy
// locate the Plug-In by identifier var aPlugin = PlugIn.find("com.YourIdentifier.NameOfApp") if (aPlugin == null){throw new Error("Plugin is not installed.")}

Identifying a Plug-In in a Script

To call a Plug-In’s actions or libraries in a script, you’ll need to identify the Plug-In using the ID assigned to by the developer.

Some Plug-In developers include a script for displaying information about the Plug-In:

info-dialog

Here’s a script that will present a dialog listing the names and IDs of the installed Plug-Ins:

plugins = PlugIn.all if (plugins.length == 0){ errTitle = 'NO PLUGINS' errMsg = 'No PlugIns are installed.' new Alert(errTitle, errMsg).show(function(result){ throw new Error('script cancelled') }) } else { pluginData = plugins.map(function(plugin){ return plugin.displayName + ":\n" + plugin.identifier + "\n" }) pluginMessage = pluginData.join('\n') new Alert('INSTALLED PLUGINS',pluginMessage).show(function(result){}) }
omnigraffle:///omnijs-run?script=plugins%20%3D%20PlugIn%2Eall%0Aif%20%28plugins%2Elength%20%3D%3D%200%29%7B%0A%09errTitle%20%3D%20%27NO%20PLUGINS%27%0A%09errMsg%20%3D%20%27No%20PlugIns%20are%20installed%2E%27%0A%09new%20Alert%28errTitle%2C%20errMsg%29%2Eshow%28function%28result%29%7B%0A%09%09throw%20new%20Error%28%27script%20cancelled%27%29%0A%09%7D%29%0A%7D%20else%20%7B%0A%09pluginData%20%3D%20plugins%2Emap%28function%28plugin%29%7B%0A%09%09return%20plugin%2EdisplayName%20%2B%20%22%3A%5Cn%22%20%2B%20plugin%2Eidentifier%20%2B%20%22%5Cn%22%0A%09%7D%29%0A%09pluginMessage%20%3D%20pluginData%2Ejoin%28%27%5Cn%27%29%0A%09new%20Alert%28%27INSTALLED%20PLUGINS%27%2CpluginMessage%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D
omnioutliner:///omnijs-run?script=plugins%20%3D%20PlugIn%2Eall%0Aif%20%28plugins%2Elength%20%3D%3D%200%29%7B%0A%09errTitle%20%3D%20%27NO%20PLUGINS%27%0A%09errMsg%20%3D%20%27No%20PlugIns%20are%20installed%2E%27%0A%09new%20Alert%28errTitle%2C%20errMsg%29%2Eshow%28function%28result%29%7B%0A%09%09throw%20new%20Error%28%27script%20cancelled%27%29%0A%09%7D%29%0A%7D%20else%20%7B%0A%09pluginData%20%3D%20plugins%2Emap%28function%28plugin%29%7B%0A%09%09return%20plugin%2EdisplayName%20%2B%20%22%3A%5Cn%22%20%2B%20plugin%2Eidentifier%20%2B%20%22%5Cn%22%0A%09%7D%29%0A%09pluginMessage%20%3D%20pluginData%2Ejoin%28%27%5Cn%27%29%0A%09new%20Alert%28%27INSTALLED%20PLUGINS%27%2CpluginMessage%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D

Summary

Omni Automation Plug-Ins provide the means for delivering automation functionality integrated into the host application’s environment. A Plug-In’s actions (scripts) may be supported by libraries and resources contained within the hosting Plug-In’s bundle. Plug-In actions are made available to the user as menu items on the host application’s Script menu, or as actions assigned through the application interface to document or object event triggers.

Continue to the next section to learn how to create Plug-In actions.

UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER