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. Omni Automation plug-ins may created as either solitary files containing a single action, or as bundle files containing or more actions, libraries, and other supporting files and images.

This section details the design of bundle plug-ins, beginning a description of two potential bundle components:

The Plug-In Bundle

Omni Automation bundle 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.

BUNDLE TEMPLATE DOWNLOADS

To assist you in understanding and creating your own Plug-Ins:

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.NameOfPlugIn", "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. (Note the inclusion of an ending semicolon character)

The Resources folder

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

plugin-anatomy

IMPORTANT: In the illustration of the plug-in folder heirarchy, the placeholders for the libary and action file names are encased within < > characters. Replace these placeholders with the file names of the individual action and library files. TIP: use filenames without spaces: my-action-filename.js, my-action-filename.strings

// locate the Plug-In by identifier var aPlugin = PlugIn.find("com.YourIdentifier.NameOfPlugIn") 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

New File Extension Support

The file extensions used for Omni Automation plug-ins now include app-specific extensions for single-file plug-ins, matching those currently used for plug-in bundles. These changes will be reflected in each of the Omni applications as they are updated over the following months. (posted 7/2020)

The five supported file extensions are:

With the new app-specific file extension support, the plug-in installation process is simplified:

App-specific plug-in file extension support appears in these versions:

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