Omni Automation Plugins

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

Example PlugIn for OmniGraffle

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

The video below shows how to install the example plugin on iOS, and how to access the functions of the plugIn:

The PlugIn Bundle

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

To assist you in understanding and creating your own plugins, you can download a simplified OmniGraffle plugin template here and an OmniOutliner plugin template here. To open the unarchived plugin 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 PlugIn bundle:

plugin-anatomy

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

The Manifest

The plugin 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 plugin’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 plugin, and the description key is a short explanation of the plugin’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 plugin. 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 plugin. 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 plugin name that should be displayed to the user in any menus. The key of the manifest.strings file is the value of the plugin identifier key from the manifest.json file. The value of the key is the localized string for the plugin name.

The Resources folder

The Resources folder contains all other plugin components, including:

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

Identifying a PlugIn in a Script

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

Some PlugIn developers include a script for displaying information about the plugin:

info-dialog

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

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 PlugIns provide the means for delivering automation functionality integrated into the host application’s environment. A plugin’s actions (scripts) may be supported by libraries and resources contained within the hosting plugin’s bundle. Plugin 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 plugin 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