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:

Actions • are Omni Automation scripts that perform automation tasks. Actions can be selected from its host Plug-In’s sub-menu displayed in the application’s Scripts menu, or may be assigned to documents or objects to run when triggered through user interaction. Actions can even be added by the user to the application’s toolbar, and there is no minimum or limit on the number of actions a Plug-In may provide.
Libraries • are JavaScript files containing specialized automation routines or functions, usually related to a single topic or purpose. The functions of a library can be accessed by both actions and external Omni Automation scripts. A Plug-In may contain no or multiple libraries.

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:

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

The manifest.json file is a JSON (JavaScript Object Notation) document that details the Plug-In’s essential information and components
The Resources folder contains all Plug-In elements aside from the manifest.json file

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" } ] }

Plug-In Manifest JSON

{

"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 “manifest.strings” File

"com.PlugInAuthorID.OmniGraffle" = "PlugIn for OmniGraffle"

The Resources folder

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

Actions • Actions are JavaScript scripts written using Omni Automation and are saved as text files with the file extension of: .js
Libraries • Libraries are also JavaScript scripts containing one or functions written using Omni Automation and are saved as text files with the file extension of: .js
Toolbar Icons • Are small images that are placed by the user on the application’s toolbar to provide a direct touch|click means for executing the Plug-In action.
Other resources • Omni Automation Plug-Ins may contain their own optional resources such as images, databases, and text files. These items may be accessed by the Plug-In’s actions.

Localized Project Folders • Because Omni Automation Plug-Ins may be designed to work with multiple languages, localization tables that match user-visible text to corresponding translations are placed within project folders whose name begins with the standard locale abbreviation for the target language, and end with the file extension of: lproj
For example, the localized project folder for U.S. English is named: en.lproj and the localized project folder for French is: fr.lproj Each language gets its own localized project folder.
Within the localized project folder are placed text files (with file extension: .strings) for each action and library file contained in the top-level of the Resources folder. These files are covered in detail in the Actions and Libraries sections of this website.

// 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.

Identify a Plug-In

// locate the Plug-In by identifier

var aPlugin = PlugIn.find("com.YourIdentifier.NameOfApp")

if (aPlugin == null){throw new Error("Plug-In is not installed.")}

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

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

Show Name and ID of Installed Plug-Ins

plugins = PlugIn.all

if (plugins.length == 0){

errTitle = 'No Plug-Ins'

errMsg = 'No Plug-Ins 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 PLUG-INS',pluginMessage).show(function(result){})

}

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

Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. OMNI-AUTOMATION.COM assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. OMNI-AUTOMATION.COM provides this only as a convenience to our users. OMNI-AUTOMATION.COM has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and OMNI-AUTOMATION.COM assumes no responsibility in this regard. Please understand that a third-party site is independent from OMNI-AUTOMATION.COM and that OMNI-AUTOMATION.COM has no control over the content on that website. Please contact the vendor for additional information.