Omni Automation Libraries

Calling Omni Automation Libraries

This section examines how to access the functions placed within a library and how to “load” and “call” an installed library from a script URL.

Loading the Installed Library

To access the functions placed within an installed library, a script must first generate an object reference to the library. To do so requires two bits of information:

The identifier of the PlugIn containing the library. For single-file libraries, this identifier should be declared in the metadata at the top of the library code.
The name of the library, which is the name of the library file without the file extension.

The following function will return an object reference to a specified library, or halt the script by displaying an error alert if either the hosting plugIn or library are not installed.

Load Specified Library

function loadLibrary(plugInID,libraryName){

try {

plugInIDs = PlugIn.all.map(function(plugin){return plugin.identifier})

if (plugInIDs.includes(plugInID)){

plugIn = PlugIn.find(plugInID)

} else {throw new Error("PlugIn not installed")}

libraryNames = plugIn.libraries.map(function(library){return library.name})

if (libraryNames.includes(libraryName)){

return plugIn.library(libraryName)

} else {throw new Error("Library not in PlugIn")}

} catch(err){

errTitle = "MISSING RESOURCE"

alert = new Alert(errTitle,err.message).show(function(result){})

throw err.message

}

01-16 The function takes an input parameters the hosting PlugIn identifier and the library name.

02-15 An error handler for catching and displaying an error message in an alert dialog.

03 Generate an array of the IDs of all installed PlugIns.

04 A conditional statement to verify that the passed-in PlugIn ID is in the array of PlugIn IDs. If not, throw an error to inform the user that the host PlugIn is not installed.

05 Use the find() method of the PlugIn class to generate an object reference to the host PlugIn

07 Generate an array of the names of all of the host PlugIn’s libraries.

08 A conditional statement to verify that the passed-in library name is in the array of library names. If not, throw an error to inform the user that the library is not installed in the host PlugIn.

09 Use the library() method of the PlugIn class to return an object reference to the library.

Calling Library Functions

The “loaded” library object can then be used to call the functions within the library:

Calling Library Function

libraryReference.functionName(optionalPassedParameter,etc.)

Here’s an example script that uses a function from the ShapeLib library to create multiple shapes on the current canvas in OmniGraffle: (install shape library below before running script)

function loadLibrary(plugInID,libraryName){ try { plugInIDs = PlugIn.all.map(function(plugin){return plugin.identifier}) if (plugInIDs.includes(plugInID)){ plugIn = PlugIn.find(plugInID) } else {throw new Error("PlugIn not installed")} libraryNames = plugIn.libraries.map(function(library){return library.name}) if (libraryNames.includes(libraryName)){ return plugIn.library(libraryName) } else {throw new Error("Library not in PlugIn")} } catch(err){ errTitle = "MISSING RESOURCE" alert = new Alert(errTitle,err.message).show(function(result){}) throw err.message } } shapeLib = loadLibrary("com.omni-automation.libraries.ShapeLib","ShapeLib") shapeLib.addShapeWithParameters( 'Star', // shape type new Rect(0,0,100,100), // shape rect Color.yellow, // fill color Color.red, // stroke color 4 // stroke thickness ) shapeLib.addShapeWithParameters( 'Circle', new Rect(110,0,100,100), Color.green, Color.blue, 4 ) shapeLib.addShapeWithParameters( 'Diamond', new Rect(220,0,100,100), Color.red, Color.gray, 4 )

omnigraffle://localhost/omnijs-run?script=try%7Bfunction%20loadLibrary%28plugInID%2ClibraryName%29%7B%0A%09try%20%7B%0A%09%09plugInIDs%20%3D%20PlugIn%2Eall%2Emap%28function%28plugin%29%7Breturn%20plugin%2Eidentifier%7D%29%0A%09%09if%20%28plugInIDs%2Eincludes%28plugInID%29%29%7B%0A%09%09%09plugIn%20%3D%20PlugIn%2Efind%28plugInID%29%20%0A%09%09%7D%20else%20%7Bthrow%20new%20Error%28%22PlugIn%20not%20installed%22%29%7D%0A%09%09libraryNames%20%3D%20plugIn%2Elibraries%2Emap%28function%28library%29%7Breturn%20library%2Ename%7D%29%0A%09%09if%20%28libraryNames%2Eincludes%28libraryName%29%29%7B%0A%09%09%09return%20plugIn%2Elibrary%28libraryName%29%0A%09%09%7D%20else%20%7Bthrow%20new%20Error%28%22Library%20not%20in%20PlugIn%22%29%7D%0A%09%7D%20catch%28err%29%7B%0A%09%09errTitle%20%3D%20%22MISSING%20RESOURCE%22%0A%09%09alert%20%3D%20new%20Alert%28errTitle%2Cerr%2Emessage%29%2Eshow%28function%28result%29%7B%7D%29%0A%09%09throw%20err%2Emessage%0A%09%7D%0A%7D%0AshapeLib%20%3D%20loadLibrary%28%22com%2Eomni%2Dautomation%2Elibraries%2EShapeLib%22%2C%22ShapeLib%22%29%0AshapeLib%2EaddShapeWithParameters%28%0A%09%27Star%27%2C%20%2F%2F%20shape%20type%0A%09new%20Rect%280%2C0%2C100%2C100%29%2C%20%2F%2F%20shape%20rect%0A%09Color%2Eyellow%2C%20%2F%2F%20fill%20color%0A%09Color%2Ered%2C%20%2F%2F%20stroke%20color%0A%094%20%2F%2F%20stroke%20thickness%0A%29%0AshapeLib%2EaddShapeWithParameters%28%0A%09%27Circle%27%2C%0A%09new%20Rect%28110%2C0%2C100%2C100%29%2C%0A%09Color%2Egreen%2C%0A%09Color%2Eblue%2C%0A%094%0A%29%0AshapeLib%2EaddShapeWithParameters%28%0A%09%27Diamond%27%2C%0A%09new%20Rect%28220%2C0%2C100%2C100%29%2C%0A%09Color%2Ered%2C%0A%09Color%2Egray%2C%0A%094%0A%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

Calling Library Functions

shapeLib = loadLibrary("com.omni-automation.libraries.ShapeLib","ShapeLib")

shapeLib.addShapeWithParameters(

'Star', // shape type

new Rect(0,0,100,100), // shape rect

Color.yellow, // fill color

Color.red, // stroke color

4 // stroke thickness

)

shapeLib.addShapeWithParameters(

'Circle',

new Rect(110,0,100,100),

Color.green,

Color.blue,

)

shapeLib.addShapeWithParameters(

'Diamond',

new Rect(220,0,100,100),

Color.red,

Color.gray,

)

The Shape Library

Here is an example library for creating solids and text shapes in OmniGraffle.

/*{ "type": "library", "targets": ["omnigraffle"], "identifier": "com.omni-automation.libraries.ShapeLib", "version": "1.1" }*/ (() => { var ShapeLib = new PlugIn.Library(new Version("1.0")); /* libID = "com.omni-automation.libraries.ShapeLib" shapeLib = PlugIn.find(libID).library("ShapeLib") */ // creates a new shape on the current canvas using the provided parameters ShapeLib.addShapeWithParameters = function(shapeType,shapeRect,fillColorValue,strokeColorValue,strokeWidth){ // set default parameter values if omitted or null shapeType = (typeof shapeType === 'undefined' || shapeType === null) ? "Rectangle" : shapeType shapeRect = (typeof shapeRect === 'undefined' || shapeRect === null) ? new Rect(0,0,72,72) : shapeRect fillColorValue = (typeof fillColorValue === 'undefined' || fillColorValue === null) ? null : fillColorValue strokeColorValue = (typeof strokeColorValue === 'undefined' || strokeColorValue === null) ? Color.black : strokeColorValue strokeWidth = (typeof strokeWidth === 'undefined' || strokeWidth === null) ? 1 : strokeWidth // create the shape cnvs = document.windows[0].selection.canvas aShape = cnvs.addShape(shapeType, shapeRect) aShape.fillColor = fillColorValue aShape.strokeColor = strokeColorValue aShape.strokeThickness = strokeWidth aShape.shadowColor = null // return an object reference to the shape return aShape } // makes a shape on the current canvas containing indicated string or array of strings ShapeLib.addTextShape = function(stringOrArray,hAlignIndicator,textSize){ // set default parameter values if omitted or null stringOrArray = (typeof stringOrArray === 'undefined' || stringOrArray === null) ? "sample text" : stringOrArray hAlignIndicator = (typeof hAlignIndicator === 'undefined' || hAlignIndicator === null) ? 1 : hAlignIndicator textSize = (typeof textSize === 'undefined' || textSize === null) ? 12 : textSize // if input is array of strings, convert to paragraph-delimited string textInput = (stringOrArray instanceof Array) ? stringOrArray.join('\n') : stringOrArray // create the shape on the current canvas cnvs = document.windows[0].selection.canvas aShape = cnvs.newShape() aShape.autosizing = TextAutosizing.Full aShape.text = textInput aShape.textSize = textSize aShape.strokeColor = Color.black aShape.strokeThickness = 0 aShape.shadowColor = null switch (hAlignIndicator){ case 0: aShape.textHorizontalAlignment = HorizontalTextAlignment.Left break case 1: aShape.textHorizontalAlignment = HorizontalTextAlignment.Center break case 2: aShape.textHorizontalAlignment = HorizontalTextAlignment.Right break case 3: aShape.textHorizontalAlignment = HorizontalTextAlignment.Justify break } // move shape to zero origin aGeometry = aShape.geometry aGeometry.origin = Point.zero aShape.geometry = aGeometry // return an object reference to the shape return aShape } // returns a list of the default shape types ShapeLib.getDefaultShapes = function(){ return ["RoundedStack", "OrGate", "AndGate", "VerticalBrackets", "HorizontalBrackets", "Cube", "SemiCircle", "QuarterCircle", "QuarterArc", "Star", "Cross", "Cloud", "VerticalTriangle", "RightTriangle", "Cylinder", "Diamond", "VerticalArrow", "DoubleHorizontalArrow", "HorizontalArrow", "HorizontalTriangle", "House", "Subprocess", "Trapazoid", "Pentagon", "Hexagon", "Octagon", "DisplayShape", "ParallelLines", "VerticalParallelLines", "Parallelogram", "Circle", "SlopedRect", "DocumentShape", "Rectangle", "RoundRect", "Heart", "Patch", "Speech Bubble", "Bolt", "Lightning Bolt", "Sticky", "Think Bubble", "Puzzle Piece", "SingleLine", "Delete", "NoteShape", "iOSAppIcon"].sort() } // returns a list of functions ShapeLib.getLibraryFunctions = function(){ versStr = this.version.versionString functionTitles = ["addShapeWithParameters(shapeType,shapeRect,fillColorValue,strokeColorValue,strokeWidth)","addTextShape(stringOrArray,horizontalAlignmentIndex,textSize)","getDefaultShapes()"]; return "###### ShapeLib v" + versStr + " Functions #####\n\t--> " + functionTitles.join("\n\t--> "); }; return ShapeLib; })();

Shape Library

/*{

"type": "library",

"targets": ["omnigraffle"],

"identifier": "com.omni-automation.libraries.ShapeLib",

"version": "1.0"

}*/

(() => {

var ShapeLib = new PlugIn.Library(new Version("1.0"));

// creates a new shape on the current canvas using the provided parameters

ShapeLib.addShapeWithParameters = function(shapeType,shapeRect,fillColorValue,strokeColorValue,strokeWidth){

// set default parameter values if omitted or null

shapeType = (typeof shapeType === 'undefined' || shapeType === null) ? "Rectangle" : shapeType

shapeRect = (typeof shapeRect === 'undefined' || shapeRect === null) ? new Rect(0,0,72,72) : shapeRect

fillColorValue = (typeof fillColorValue === 'undefined' || fillColorValue === null) ? null : fillColorValue

strokeColorValue = (typeof strokeColorValue === 'undefined' || strokeColorValue === null) ? Color.black : strokeColorValue

strokeWidth = (typeof strokeWidth === 'undefined' || strokeWidth === null) ? 1 : strokeWidth

// create the shape

cnvs = document.windows[0].selection.canvas

aShape = cnvs.addShape(shapeType, shapeRect)

aShape.fillColor = fillColorValue

aShape.strokeColor = strokeColorValue

aShape.strokeThickness = strokeWidth

aShape.shadowColor = null

// return an object reference to the shape

return aShape

}

// makes a shape on the current canvas containing indicated string or array of strings

ShapeLib.addTextShape = function(stringOrArray,hAlignIndicator,textSize){

// set default parameter values if omitted or null

stringOrArray = (typeof stringOrArray === 'undefined' || stringOrArray === null) ? "sample text" : stringOrArray

hAlignIndicator = (typeof hAlignIndicator === 'undefined' || hAlignIndicator === null) ? 1 : hAlignIndicator

textSize = (typeof textSize === 'undefined' || textSize === null) ? 12 : textSize

// if input is array of strings, convert to paragraph-delimited string

textInput = (stringOrArray instanceof Array) ? stringOrArray.join('\n') : stringOrArray

// create the shape on the current canvas

cnvs = document.windows[0].selection.canvas

aShape = cnvs.newShape()

aShape.autosizing = TextAutosizing.Full

aShape.text = textInput

aShape.textSize = textSize

aShape.strokeColor = Color.black

aShape.strokeThickness = 0

aShape.shadowColor = null

switch (hAlignIndicator){

case 0:

aShape.textHorizontalAlignment = HorizontalTextAlignment.Left

break

case 1:

aShape.textHorizontalAlignment = HorizontalTextAlignment.Center

break

case 2:

aShape.textHorizontalAlignment = HorizontalTextAlignment.Right

break

case 3:

aShape.textHorizontalAlignment = HorizontalTextAlignment.Justify

break

}

// move shape to zero origin

aGeometry = aShape.geometry

aGeometry.origin = Point.zero

aShape.geometry = aGeometry

// return an object reference to the shape

return aShape

}

// returns a list of the default shape types

ShapeLib.getDefaultShapes = function(){

return ["RoundedStack", "OrGate", "AndGate","VerticalBrackets","HorizontalBrackets","Cube","SemiCircle","QuarterCircle","QuarterArc","Star","Cross","Cloud","VerticalTriangle","RightTriangle","Cylinder","Diamond","VerticalArrow","DoubleHorizontalArrow","HorizontalArrow","HorizontalTriangle","House","Subprocess","Trapazoid","Pentagon","Hexagon","Octagon","DisplayShape","ParallelLines","VerticalParallelLines","Parallelogram","Circle","SlopedRect","DocumentShape","Rectangle","RoundRect","Heart","Patch","Speech Bubble","Bolt","Lightning Bolt","Sticky","Think Bubble","Puzzle Piece","SingleLine","Delete","NoteShape", "iOSAppIcon"].sort()

}

// returns a list of functions

ShapeLib.getLibraryFunctions = function(){

versStr = this.version.versionString;

functionTitles = ["addShapeWithParameters(shapeType,shapeRect,fillColorValue,strokeColorValue,strokeWidth)","addTextShape(stringOrArray,horizontalAlignmentIndex,textSize)","getDefaultShapes()"];

return "###### ShapeLib v" + versStr + " Functions #####\n\t--> " + functionTitles.join("\n\t--> ");

};

return ShapeLib;

})();

01-06 Library metadata includes an array of the names of the targeted applications, and a unique string as the value for the identifier key

07-86 A function container in which holds the library

08 Place a new instance of a PlugIn library in the variable: ShapeLib

16-32 Define the function addShapeWithParameters() which can be used to create solid shapes on the current canvas

18-22 Use ternary operators to provide a default value if the user omits or provides null as a value for the function parameters. (see section below)

24-31 Create the shape using any provided parameters and return an object reference to the created shape.

35-71 Define the function addTextShape() which can be used to create text labels on the current canvas

37-39 Use ternary operators to provide a default value if the user omits or provides null as a value for the function parameters. (see section below)

41 If the text input is an array of strings, convert to a paragraph-delimited text block.

43-70 Create the text shape using the provided parameters, and return an object reference to the created shape.

Default Function Parameters

The example library contains ternary operators to allow for the use of functions where no or limited parameters are provided by the user. If a specific parameter is not provided or a null placeholder is used in place of a parameter value, default values are used in their place.

Here are examples of calling a library function, providing no or some parameters.

addTextShape(stringOrArray,horizontalAlignmentIndex,textSize) shapeLib.addTextShape() //--> creates a text shape with default contents, alignment, and size shapeLib.addTextShape("How Now Brow Cow") //--> creates a text shape with specified contents, with default alignment and size shapeLib.addTextShape(["Sal","Sue","Wanda"],2) //--> creates a text shape with specified contents, aligned to the right, with default size shapeLib.addTextShape(null,null,24) //--> creates a text shape with default contents and alignment, with specified size

Default Function Parameters

addTextShape(stringOrArray,horizontalAlignmentIndex,textSize)

shapeLib.addTextShape()

//--> creates a text shape with default contents, alignment, and size

shapeLib.addTextShape("How Now Brow Cow")

//--> creates a text shape with specified contents, with default alignment and size

shapeLib.addTextShape(["Sal","Sue","Wanda"],2)

//--> creates a text shape with specified contents, aligned to the right, with default size

shapeLib.addTextShape(null,null,24)

//--> creates a text shape with default contents and alignment, with specified size

Version

Here's how to retrieve the version of the library:

shapeLib.version.versionString

Get Library Version

shapeLib.version.versionString

List Functions

The library contains a function for retrieving a list of the functions (with parameter names) contained in the library:

Listing Library Functions

shapeLib.getLibraryFunctions()

###### ShapeLib v1 Functions #####

--> addShapeWithParameters(shapeType,shapeRect,fillColorValue,strokeColorValue,strokeWidth)

--> addTextShape(stringOrArray,horizontalAlignmentIndex,textSize)

--> getDefaultShapes()

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.