Library Plug-Ins

Omni Automation Libraries are specialized plug-ins that provide the means for storing, using, and sharing Omni Automation functions. They make automation tasks easier by dramatically shortening scripts, and they enable the ability to share useful routines with other devices.

Constructor

• new PlugIn.Library(version: Version) → (PlugIn.Library) • Returns a new Library. Typically used as a file within a Plug-In bundle, or as a solitary-file plug-in.

Instance Properties

• name (String r/o) • Returns the name of the PlugIn.Library. The name is usually the file name of the library file (without file extension).

• plugIn (PlugIn r/o) • Returns the PlugIn that contains this object.

• version (Version r/o) • Returns the Version of this library, as passed to the constructor. Use the versionString property of the Version class to get the version string.

Here is the basic template for a single-file library plug-in:

Basic Single-File Library
Copy

/*{
	"type": "library",
	"targets": ["omnigraffle","omnioutliner","omnigraffle","omniplan"],
	"identifier": "com.omni-automation.all.libraryName",
	"version": "1.0"
}*/
(() => {
	const myLibrary = new PlugIn.Library(new Version("1.0"));
  
		myLibrary.myFirstFunction = function(passedParameter){
			// function code
			return myFirstFunctionResult
		};
		
		myLibrary.mySecondFunction = function(passedParameter){
			// function code
			return mySecondFunctionResult
		};
		
		lib.info = function(){
			var libProps = Object.getOwnPropertyNames(lib)
			libProps.forEach((propName, index) => {
				if (index != 0){console.log(" ")}
				console.log("•", propName)
				var item = lib[propName]
				if (typeof item === "string"){
					console.log(item)
				} else if (typeof item === "function"){
					console.log(item.toString())
				} else if (typeof item === "object"){
					if(item instanceof Version){
						console.log(item.versionString)
					} else if(item instanceof PlugIn){
						console.log(item.identifier)
					}				
				}
			})
		};

	return myLibrary;
})();

Here’s a script demonstrating how to identify the libraries contained within a plug-in:

Get Names of Libraries within Plug-In
Copy

var plugin = PlugIn.find("com.omni-automation.all.date-library")
var libs = plugin.libraries
//--> [[object PlugIn.Library: Optional("all-date-library") v1]]
var libNames = libs.map(lib => lib.name)
console.log(libNames)
//--> ["all-date-library"]

Here’s an example script statements calling functions within a library:

Calling Library Functions
Copy

// locate the library’s parent plug-in by identifier
var plugin = PlugIn.find("com.YourIdentifier.NameOfPlugIn")
if (plugin == null){throw new Error("Library plug-in not installed.")}
// load a library identified by name
var firstLibrary = plugin.library("NameOfFirstLibrary")
// load a library identified by name
var secondLibrary = plugin.library("NameOfSecondLibrary")
// call a library function by name
var callResult = firstLibrary.nameOfLibraryFunction()
// call a library function by name
secondLibrary.nameOfLibraryFunction(callResult)

Date Library

The following example library from the Date class documentation, is a single-file plug-in containing date comparison functions. This Omni Automation library can be called from within scripts or plug-ins for any of the Omni applications. TAP|CLICK the “Download Library” button to download the library plug-in archive.

The library, once installed, can be loaded and called in scripts using the following statements:

Calling the Date Library
Copy

var plugin = PlugIn.find("com.omni-automation.all.date-library")
var dateLibrary = plugin.library("all-date-library")
// dateLibrary.function-to-call()
dateLibrary.info()

The example library includes a function titled info() that returns the names and values of all of the library’s properties and functions. Adding this function to the libraries you create is a good practice, and provides users with a quick way to learn how to use your library.

Library Info Function
Copy

lib.info = function(){
	var libProps = Object.getOwnPropertyNames(lib)
	libProps.forEach((propName, index) => {
		if (index != 0){console.log(" ")}
		console.log("•", propName)
		var item = lib[propName]
		if (typeof item === "string"){
			console.log(item)
		} else if (typeof item === "function"){
			console.log(item.toString())
		} else if (typeof item === "object"){
			if(item instanceof Version){
				console.log(item.versionString)
			} else if(item instanceof PlugIn){
				console.log(item.identifier)
			}				
		}
	})
}

NOTE: In order to have the function code returned correctly when the library info() function is called, align your functions in the library to be flushed to the left side — removing some of preceding tabs:

The Date Comparison Library
Copy Download Library

/*{
	"type": "library",
	"targets": ["omnifocus","omnigraffle","omnioutliner","omniplan"],
	"identifier": "com.omni-automation.all.date-library",
	"author": "Otto Automator",
	"version": "1.1",
	"description": "A library of date functions."
}*/
(() => {
	const lib = new PlugIn.Library(new Version("1.1"));
	
// returns true if provided date/time occurs today
lib.dateOccursToday = function(dateToCheck){
	var cal = Calendar.current
	var now = new Date()
	var midnightToday = cal.startOfDay(now)
	var dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 1
	var midnightTomorrow = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= midnightToday && dateToCheck < midnightTomorrow)
}
		
// returns true if provided date/time took place yesterday
lib.dateOccurredYesterday = function(dateToCheck){
	var cal = Calendar.current
	var now = new Date()
	var midnightToday = cal.startOfDay(now)
	var dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day - 1
	var midnightYesterday = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= midnightYesterday && dateToCheck < midnightToday)
}
		
// returns true if the provided date/time takes place tomorrow
lib.dateOccurrsTomorrow = function(dateToCheck){
	var cal = Calendar.current
	var now = new Date()
	var midnightToday = cal.startOfDay(now)
	var dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 1
	var midnightTomorrow = cal.dateFromDateComponents(dc)
	dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 2
	var dayAfterTomorrow = cal.dateFromDateComponents(dc)
	return (dateToCheck >= midnightTomorrow && dateToCheck < dayAfterTomorrow)
}
		
// returns true if the provided date/time takes place next week
lib.dateOccursNextWeek = function(dateToCheck){
	var fmatr = Formatter.Date.withStyle(Formatter.Date.Style.Short)
	var weekStart = fmatr.dateFromString('next week')
	var dc = new DateComponents()
	dc.day = 7
	var followingWeek = Calendar.current.dateByAddingDateComponents(weekStart, dc)
	return (dateToCheck >= weekStart && dateToCheck < followingWeek)
}
		
// returns true if the provided date/time takes place this month
lib.dateOccurrsThisMonth = function(dateToCheck){
	var cal = Calendar.current
	var currentMonthIndex = cal.dateComponentsFromDate(new Date()).month
	var targetMonthIndex = cal.dateComponentsFromDate(dateToCheck).month
	return (targetMonthIndex === currentMonthIndex)
}
		
// returns true if the provided date/time takes place next month
lib.dateOccurrsNextMonth = function(dateToCheck){
	var cal = Calendar.current
	var dc = cal.dateComponentsFromDate(new Date())
	dc.day = 1
	dc.month = dc.month + 1
	var nextMonth = cal.dateFromDateComponents(dc)
	var nextMonthIndex = cal.dateComponentsFromDate(nextMonth).month
	var targetMonthIndex = cal.dateComponentsFromDate(dateToCheck).month
	return (nextMonthIndex === targetMonthIndex)
}
		
// returns true if the provided date/time takes place on the provided target date
lib.dateOccursOnTargetDate = function(dateToCheck, targetDate){
	var cal = Calendar.current
	var targetDateStart = cal.startOfDay(targetDate)
	var dc = cal.dateComponentsFromDate(targetDateStart)
	dc.day = dc.day + 1
	var dayAfterTargetDate = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= targetDateStart && dateToCheck < dayAfterTargetDate)
}
		
lib.info = function(){
	var libProps = Object.getOwnPropertyNames(lib)
	libProps.forEach((propName, index) => {
		if (index != 0){console.log(" ")}
		console.log("•", propName)
		var item = lib[propName]
		if (typeof item === "string"){
			console.log(item)
		} else if (typeof item === "function"){
			console.log(item.toString())
		} else if (typeof item === "object"){
			if(item instanceof Version){
				console.log(item.versionString)
			} else if(item instanceof PlugIn){
				console.log(item.identifier)
			}				
		}
	})
}

	return lib;
})();

Calling the Library

Here’s an example script calling the single-file library from another script or plug-in:

Call Date Comparison Library
Copy

var plugin = PlugIn.find("com.omni-automation.all.date-library")
var dateLibrary = plugin.library("all-date-library")
var date = new Date(new Date().setHours(25, 15, 0))
if (dateLibrary.dateOccurrsTomorrow(date)){console.log("Tomorrow!")}

If the library is part of a plug-in bundle, it can be called by simply appending the library file name (no file extension) to the “this” keyword. Here’s the code for a example bundle plug-in action that calls a library in the bundle:

Calling a Bundle Plug-In Library
Copy

(() => {
	const action = new PlugIn.Action(function(selection, sender){		
		this.library("all-date-library").info()
	})

	action.validate = function(selection, sender){
		return true
	};
	
	return action;
})();