Omni Automation Libraries

For those wishing to automate their Omni applications, libraries are your best friend.

Omni Automation Libraries provide the means for storing, using, and sharing your favorite Omni Automation functions. They can make your automation tasks easier by dramatically shortening your scripts, and they enable the ability to share useful routines with other computers and tablets.

Script Libraries exist as JavaScript script files (.js) placed within the Resources folder in plugin bundles. The functions contained within a Omni Automation Library can be called from within the host plugin’s actions, or by scripts executed outside of the host plugin.

This section describes the structure of an Omni Automation Library, how it is registered in its host plugin, and how it is referenced by plugin actions and external scripts.

The Structure of an Omni Automation Library

An Omni Automation Library is essentially a JavaScript script, comprised of a single function that is executed when the library is called (line 16). Within the main function (line 1 ~ line 15) a library object is created (line 2), and the various library functions are added to the library object (line 4, line 9). The main script finishes by returning the created library object populated with the handlers you added (line 14).

var _ = function() { var myLibrary = new PlugIn.Library(new Version("0.1")); myLibrary.myFirstFunction = function(passedParameter){ // function code return myFirstFunctionResult } myLibrary.mySecondFunction = function(passedParameter){ // function code return mySecondFunctionResult } return myLibrary; }(); _;

Libraries can contain as many functions as you find useful to include. The example shown above contains two library functions that can be called from within your plugins or scripts.

Library files are saved with the file extension: .js (which stands for JavaScript) and are placed in the Resources folder in the plugin bundle. IMPORTANT: it is best to avoid using spaces in the filenames of your libraries.

Registering an Omni Automation Library

In order to be available to the user, libraries must be registered by including them in the plugin’s manifest.json file. This file contains metadata about the plugin, as well an array of plugin actions (line 7), and an optional array of one or more libraries (line 17).

Each action element is comprised of a key:value pair for the action’s identifier (filename) (lines 9, 13) and the filename of its corresponding toolbar icon image file (lines 10, 14).

Each library element is comprised of a key:value pair (lines 19, 22) for the library’s identifier, which is the library’s filename without the file extension.

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

Calling Omni Automation Libraries within a Plugin Action

The example code shown below is of a plugin action. It is comprised of two sections: the validation code (line 14), and the execution code (line 4).

The validation section (line 14) is used to determine if the action should execute, based upon whether or not there is a selection in the frontmost document. If your action does not rely upon a selection, simply return true (15) as shown in the example.

var _ = function(){ var action = new PlugIn.Action(function(selection){ // reference libraries within host plugin var stencilLib = this.StencilLib; var shapeLib = this.ShapeLib; // call library functions using references var names = stencilLib.getStencilNames() aGraphic = shapeLib.shapeWithContentsOfArray(names) // select the created graphic document.windows[0].selection.view.select([aGraphic]) }); // validation function determines if menu item is enabled action.validate = function(selection){ return true }; return action; }(); _;

Loading a library is accomplished by simply appending the library identifier (filename) to the global object: this. In the example shown above two libraries are loaded into variables (line 4, 5).

Once the libraries have been loaded, any library functions can be called by appending the name of the function to the variable representing the host library (lines 7, 8).

Calling an Omni Automation Library within a Script

Calling into libraries within an external script is a slightly more involved process in that you must first identify the plugin that contains the library whose functions you wish to access.

In the example below, the plugin is located using the find method on the Plugin class, and the plugin’s identifier. If the plugin is installed, then an object reference to the plugin is returned and stored in a variable (line 2). If the plugin is not installed, a value of null will be returned and the next line in the script (line 3) will throw an error indicating its status as missing.

Once the plugin has been successfully identified, any libraries can be loaded using the library method on the plugin reference stored previously in a variable (lines 5, 7).

Once the library or libraries have been loaded, their functions can be accessed by appending the function name to the variable containing the loaded library (lines 9, 11).

// locate the plugin by identifier var aPlugin = PlugIn.find("com.YourIdentifier.NameOfApp") if (aPlugin == null){throw new Error("Plugin is not installed.")} // load a library identified by name var firstLibrary = aPlugin.library("NameOfFirstLibrary") // load a library identified by name var secondLibrary = aPlugin.library("NameOfSecondLibrary") // call a library function by name var aVariable = firstLibrary.nameOfLibraryFunction() // call a library function by name secondLibrary.nameOfLibraryFunction(aVariable)

Example Library

As an example, here’s a library for working with OmniGraffle stencils (see below). It contains the following functions that can be called from within console scripts and web and Omni object-links:

var _ = function() { var StencilLib = new PlugIn.Library(new Version("1.0")); // returns an array of the names of the installed stencils StencilLib.getStencilNames = function() { stencilNames = new Array() app.stencils.forEach(function(aStencil){ stencilNames.push(aStencil.name) }) return stencilNames } // imports a specified graphic from the specified stencil to the canvas StencilLib.importNamedGraphicFromNamedStencil = function(graphicName, stencilName){ for(i = 0; i < app.stencils.length; i++) { let stencil = app.stencils[i]; if (stencil.name.localeCompare(stencilName) == 0) { stencil.load(function(s) { console.log("Loaded stencil: “" + s.name + "”") for(q = 0; q < s.graphics.length; q++){ aGraphicName = s.graphics[q].name if (aGraphicName != null){ if (aGraphicName.localeCompare(graphicName) == 0){ console.log("found graphic: “" + graphicName + "”") aStencilGraphic = s.graphics[q] rsltArray = canvases[0].duplicate([aStencilGraphic]) aGraphic = rsltArray[0] aGraphic.geometry = new Rect(0, 0, aGraphic.geometry.width, aGraphic.geometry.height) document.windows[0].selection.view.select([aGraphic]) console.log("added graphic: “" + graphicName + "”") return aGraphic } } } throw new Error("Graphic “" + graphicName + "” is not in stencil “" + stencilName + "”") }) } } } // imports all graphics from the specified stencil to the canvas StencilLib.importAllGraphicsFromNamedStencil = function(stencilName){ for(i = 0; i < app.stencils.length; i++) { let stencil = app.stencils[i] if (stencil.name.localeCompare(stencilName) == 0) { stencil.load(function(s) { console.log("Loaded stencil: “" + s.name + "”") canvases[0].duplicate(s.graphics) return true }) } } } // returns the names of all graphics from the specified stencil StencilLib.getGraphicNamesForNamedStencil = function(stencilName){ var graphicNames = new Array() for(i = 0; i < app.stencils.length; i++) { let stencil = app.stencils[i] if (stencil.name.localeCompare(stencilName) == 0) { stencil.load(function(s) { console.log("Loaded stencil: “" + s.name + "”") stencil.graphics.forEach(function(aGraphic){ graphicNames.push(aGraphic.name) }) return graphicNames }) } } return graphicNames } return StencilLib; }(); _;

Here’s an example of calling the previous example Stencil Library:

aPlugin = PlugIn.find("com.NyhthawkProductions.OmniGraffle") stencilLib = aPlugin.library("StencilLib") stencilLib.importNamedGraphicFromNamedStencil('Tablet Mac','Google Material Design Icons')
import-from-stencil
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