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

plugin = PlugIn.find("com.omni-automation.all.date-library")
libs = plugin.libraries
//--> [[object PlugIn.Library: Optional("all-date-library") v1]]
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
plugin = PlugIn.find("com.YourIdentifier.NameOfPlugIn")
if (!plugin){throw new Error("Library plug-in not installed.")}
// load a library identified by name
firstLibrary = plugin.library("NameOfFirstLibrary")
// load a library identified by name
secondLibrary = plugin.library("NameOfSecondLibrary")
// call a library function by name
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

plugin = PlugIn.find("com.omni-automation.all.date-library")
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(){
	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
OmniFocusOmniGraffleOmniOutlinerOmniPlan  

/*{
	"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){
	cal = Calendar.current
	now = new Date()
	midnightToday = cal.startOfDay(now)
	dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 1
	midnightTomorrow = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= midnightToday && dateToCheck < midnightTomorrow)
}
		
// returns true if provided date/time took place yesterday
lib.dateOccurredYesterday = function(dateToCheck){
	cal = Calendar.current
	now = new Date()
	midnightToday = cal.startOfDay(now)
	dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day - 1
	midnightYesterday = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= midnightYesterday && dateToCheck < midnightToday)
}
		
// returns true if the provided date/time takes place tomorrow
lib.dateOccurrsTomorrow = function(dateToCheck){
	cal = Calendar.current
	now = new Date()
	midnightToday = cal.startOfDay(now)
	dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 1
	midnightTomorrow = cal.dateFromDateComponents(dc)
	dc = cal.dateComponentsFromDate(midnightToday)
	dc.day = dc.day + 2
	dayAfterTomorrow = cal.dateFromDateComponents(dc)
	return (dateToCheck >= midnightTomorrow && dateToCheck < dayAfterTomorrow)
}
		
// returns true if the provided date/time takes place next week
lib.dateOccursNextWeek = function(dateToCheck){
	fmatr = Formatter.Date.withStyle(Formatter.Date.Style.Short)
	weekStart = fmatr.dateFromString('next week')
	dc = new DateComponents()
	dc.day = 7
	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){
	cal = Calendar.current
	currentMonthIndex = cal.dateComponentsFromDate(new Date()).month
	targetMonthIndex = cal.dateComponentsFromDate(dateToCheck).month
	return (targetMonthIndex === currentMonthIndex)
}
		
// returns true if the provided date/time takes place next month
lib.dateOccurrsNextMonth = function(dateToCheck){
	cal = Calendar.current
	dc = cal.dateComponentsFromDate(new Date())
	dc.day = 1
	dc.month = dc.month + 1
	nextMonth = cal.dateFromDateComponents(dc)
	nextMonthIndex = cal.dateComponentsFromDate(nextMonth).month
	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){
	cal = Calendar.current
	targetDateStart = cal.startOfDay(targetDate)
	dc = cal.dateComponentsFromDate(targetDateStart)
	dc.day = dc.day + 1
	dayAfterTargetDate = cal.dateFromDateComponents(dc)
	return ( dateToCheck >= targetDateStart && dateToCheck < dayAfterTargetDate)
}
		
lib.info = function(){
	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

plugin = PlugIn.find("com.omni-automation.all.date-library")
dateLibrary = plugin.library("all-date-library")
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;
})();