Script Links

An exciting aspect of automation is its ability to be expressed as URLs. OmniJS 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 OmniJS scripts into URLs. Simply pass in the name of the Omni application to target, and the script code.

function encodeForOmniJS(OmniAppName, scriptCode){ appName = OmniAppName.toLowerCase() urlOpening = appName + ":///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") 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.

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.


Here are some examples of how web-based OmniJS links can be used.

Blending OmniJS with HTML Elements

OmniJS URLs can be integrated with standard HTML elements like forms to create graphic-oriented interfaces that deliver the power of scripting via webpages.

Give it a try! First, open a document in OmniGraffle, then:

Add a Shape:

tap|click the popup menus to select a fill color and a stroke color:

var aRect = new Rect(100,100,200,200) var aFillColor = Color.RGBXXXXX var aStrokeColor = Color.RGBYYYYY var aShape =[0].selection.canvas.addShape('ZZZZZ', aRect) aShape.strokeThickness = 12 aShape.fillColor = aFillColor aShape.strokeColor = aStrokeColor
Fill:  Stroke: 

Next, tap|click a shape to add it to the current OmniGraffle document:

star-white circle-white diamond-white square-white

OmniJS Web-links in Split-Screen

Here’s a short video showing the use of OmniJS weblinks in split-screen mode on both iOS and macOS:

OmniGraffle is all about visualizing concepts and data. This video shows an example of using web-based data to “heat map” an OmniGraffle object, in this case a map of the states of the United States. Heat-Mapping is a common technique used in business presentations because it shows data in terms of intensity, revealing “hot spots.”

In this example two scripts work together to transfer and apply the data from the webpage to the OmniGraffle document.

The webpage contains an embedded JavaScript function that is triggered by a click or tap on the OmniGraffle icon at the top right of the table. Once launched, the JavaScript script in the webpage:

Once approved by the user, the URL is received by OmniGraffle, decoded, and its OmniJS script is extracted from the URL. OmniGraffle then displays the script to the user for review and acceptance. If the user taps (clicks) the Run Script button, the script is executed by OmniGraffle. The OmniJS script:

And it all happens in seconds, triggered by a single tap or click. Now that's the power of automation!

Try it yourself!

STEP 1: click or tap here to download the OmniGraffle document shown in the video.

STEP 2: display the webpage containing the table data by clicking or tapping here.

For future use, you can click or tap here to download the OmniGraffle USA Map stencil.


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