Script Links

An exciting aspect of Omni Automation is its ability to be expressed as URLs. Omni Automation URLs can be used to communicate between applications in both macOS and iOS, may be embedded in HTML documentation and webpages as clickable links.

Encoding Scripts for URLs

JavaScript scripts are able to be included in URLs because they are encoded using a standard method called “percent encoding.” With percent encoding, spaces and special characters are expressed as the percent character (%) followed by a two-character string. For example, a space is percent encoded as %20, a quote mark is %22, and a carriage return is represented as %3D.

Percent encoding enables complex scripts to be useable in URLs. And fortunately, the ability to encode strings with percent encoding is part of the standard JavaScript architecture. Here is a function for encoding Omni Automation scripts into URLs. Simply pass in the name of the Omni application to target, and the script code.

function encodeForOmniAutomation(OmniAppName, scriptCode){ appName = OmniAppName.toLowerCase() urlOpening = appName + "://localhost/omnijs-run?script=" var encodedScript = encodeURIComponent(scriptCode) encodedScript = encodedScript.split("'").join("%27") encodedScript = encodedScript.split("(").join("%28") encodedScript = encodedScript.split(")").join("%29") encodedScript = encodedScript.split("!").join("%21") encodedScript = encodedScript.split("~").join("%7E") encodedScript = encodedScript.split(".").join("%2E") encodedScript = encodedScript.split("_").join("%5F") encodedScript = encodedScript.split("*").join("%2A") encodedScript = encodedScript.split("-").join("%2D") return urlOpening + encodedScript }

You can use this function in your scripts or include it in your webpage design to enable your pages to offer clickable-scripts.

Omni Automation scripts can receive information from and be executed by JavaScript scripts hosted in web pages.

So the first step in creating a script link is to copy a script like this one that creates a blue star shape on the current canvas in OmniGraffle, and pass it to the encoding routine:

aRect = new Rect(0, 0, 200, 200) aColor = Color.RGB(0, 0, 1, 1) aShape = canvases[0].addShape('Star', aRect) aShape.fillColor = aColor

which will turn it into a URL like this:

And here is the encoded URL used in an HTML weblink:

<a href="omnigraffle:///omnijs-run?script=aRect%20%3D%20new%20Rect%280%2C%200%2C%20200%2C%20200%29%0AaColor%20%3D%20Color%2ERGB%280%2C%200%2C%201%2C%201%29%0AaShape%20%3D%20canvases%5B0%5D%2EaddShape%28%27Star%27%2C%20aRect%29%0AaShape%2EfillColor%20%3D%20aColor">Add a Blue Star</a>

Try it Yourself!

As an example, the encoding routine is included in this webpage and connected to the form below so you can try it yourself! Paste the “Blue Star” script example (shown above) into the field and click the Encode Script button and the script will be replaced with the encoded URL. Click the Run Script button and the encoded script will be executed.

NOTE: Detailed information and examples concerning the use of Omni Automation with HTML is available in the “Omni-Interactive HTML” section of this website.

Encoding and Running Omni Automation using Swift

According to Apple, Swift is a powerful and intuitive programming language for macOS, iOS, watchOS and tvOS. Writing Swift code is interactive and fun, the syntax is concise yet expressive, and Swift includes modern features developers love. Swift code is safe by design, yet also produces software that runs lightning-fast.

The following is an example of how to encode and run Omni Automation scripts using the Swift language:

You can download the .swift file here.

import Foundation import AppKit func executeOmniGraffleScript (scriptString:String) { let encodedScript = scriptString.addingPercentEncoding(withAllowedCharacters: .alphanumerics) let omniAScriptURLStr = "omnigraffle://localhost/omnijs-run?script=" + encodedScript! let url = URL(string: omniAScriptURLStr)!) // macOS } func executeOmniOutlinerScript (scriptString:String) { let encodedScript = scriptString.addingPercentEncoding(withAllowedCharacters:.alphanumerics) let omniAScriptURLStr = "omnioutliner://localhost/omnijs-run?script=" + encodedScript! let url = URL(string: omniAScriptURLStr)!) } var OmniGraffleScript = """ var aRect = new Rect(100,100,200,200) var aFillColor = Color.RGB(0, 0, 1, 1) var aStrokeColor = cnvs =[0].selection.canvas var aShape = cnvs.addShape('Circle',aRect) aShape.strokeThickness = 12 aShape.fillColor = aFillColor aShape.strokeColor = aStrokeColor """ var OmniOutlinerScript = """ names = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"] names.forEach(function(name){ rootItem.addChild(null,function(item){item.topic = name}) }) """ executeOmniGraffleScript(scriptString:OmniGraffleScript) // executeOmniOutlinerScript(scriptString:OmniOutlinerScript)

Encoding and Running Omni Automation using AppleScriptObj-C

AppleScriptObj-C is a powerful fusion of the AppleScript and Objective-C languages that enables standard AppleScript code to access macOS frameworks. The following example demonstrates the use of AppleScriptObj-C to execute an Omni Automation script copied to the clipboard:

use AppleScript version "2.4" -- Yosemite (10.10) or later use framework "Foundation" use scripting additions -- classes, constants, and enums used property NSCharacterSet : a reference to current application's NSCharacterSet property NSString : a reference to current application's NSString try display dialog "Execute the Omni Automation code on the clipboard with which application?" buttons {"Cancel", "OmniOutliner", "OmniGraffle"} default button 1 with icon 1 set applicationName to button returned of the result if applicationName is "OmniOutliner" then set appID to "com.omnigroup.OmniOutliner5" else set appID to "com.omnigroup.OmniGraffle7" end if set lowercaseAppName to my changeCaseOfText(applicationName, 1) set clipboardScript to get the clipboard set textWithErrorHandler to "try{" & clipboardScript & "}catch(err){console.log(err)}" set encodedString to my encodeUsingPercentEncoding(textWithErrorHandler) set the scriptURL to lowercaseAppName & "://localhost/omnijs-run?script=" & encodedString tell application id appID activate tell current application open location scriptURL end tell end tell on error errorMessage number errorNumber activate if errorNumber is not -128 then activate display alert (errorNumber as string) message errorMessage end if end try on encodeUsingPercentEncoding(sourceText) -- create a Cocoa string from the passed AppleScript string, by calling the NSString class method stringWithString: set the sourceString to NSString's stringWithString:sourceText -- indicate the allowed characters that do not get encoded set allowedCharacterSet to NSCharacterSet's alphanumericCharacterSet -- apply the indicated transformation to the Cooca string set the adjustedString to the sourceString's stringByAddingPercentEncodingWithAllowedCharacters:(allowedCharacterSet) -- convert from Cocoa string to AppleScript string return (adjustedString as string) end encodeUsingPercentEncoding on changeCaseOfText(sourceText, caseIndicator) -- create a Cocoa string from the passed text, by calling the NSString class method stringWithString: set the sourceString to NSString's stringWithString:sourceText -- apply the indicated transformation to the Cocoa string if the caseIndicator is 0 then set the adjustedString to sourceString's uppercaseString() else if the caseIndicator is 1 then set the adjustedString to sourceString's lowercaseString() else set the adjustedString to sourceString's capitalizedString() end if -- convert from Cocoa string to AppleScript string return (adjustedString as string) end changeCaseOfText

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.