Templates for 3rd-Party JavaScript Actions
Some iOS apps, such as Drafts and 1Writer, support user-automation in the form of customizable JavaScript scripts (actions) that can contain commands for accessing and controlling most aspects of the apps, as well as supporting the methods and constructs of Core JavaScript.
The following templates can be used as scripts (actions) in these apps to additionally execution Omni Automation scripts that optionally may receive text input for processing.
Run Omni Automation Script with No Input
The first script template executes an Omni Automation script without input.
| Template: Omni Automation Script with No Input | ||
| 01 | (() => { | |
| 02 | function OmniAutomationFunction(){ | |
| 03 | // Omni Automation script goes here | |
| 04 | }; | |
| 05 | ||
| 06 | app.openURL( | |
| 07 | 'lowercaseOmniAppName://localhost/omnijs-run?script=' + | |
| 08 | encodeURIComponent( | |
| 09 | '(' + OmniAutomationFunction + ')' + '()' | |
| 10 | ) | |
| 11 | ); | |
| 12 | })(); | |
01-12 Wrapping the script action in a self-invoking anonymous arrow function (() => {//code})(); prevents conflicts between other script actions, run in sequence, that may use the same variables.
02-04 The Omni Automation script is placed within a function to enable it to be converted to text for inclusion later in an Omni Automation script URL.
03 Place the Omni Automation script code within the function
06-11 The host application uses the JavaScript method openURL() for opening the URL generated by within the arguments parens.
07 The Omni Automation script URL begins with the name of the targeted Omni application in lowercase characters, like: omnigraffle, or omnioutliner and is followed by the omnijs-run command with the script parameter. See this page for details about Omni Automation script links.
08-10 The standard JavaScript method encodeURIComponent() is used to percent encode the Omni Automation script, and the resulting string is then appended to the URL opening.
09 The function and optional arguments are placed with adjacent parens for execution (function)(arguments). In this example, there are no arguments so an empty parens set is used.
| DO THIS ► | To use this template to create a new JavaScript script action in Drafts or 1Writer, copy the template into a new script, and then replace the placeholder at 03 with the Omni Automation script to run, and replace the placeholder at 07 with the lowercase name of the Omni Application to target. |
For example, here is an action for creating a formatted circle on the current canvas of the open OmniGraffle document:
| Omni Automation Script with No Input | ||
| 01 | (() => { | |
| 02 | function OmniAutomationFunction(){ | |
| 03 | aRect = new Rect(100,100,200,200) | |
| 04 | aFillColor = Color.RGB(0, 0, 1, 1) | |
| 05 | aStrokeColor = Color.red | |
| 06 | cnvs = document.windows[0].selection.canvas | |
| 07 | aShape = cnvs.addShape('Circle',aRect) | |
| 08 | aShape.strokeThickness = 12 | |
| 09 | aShape.fillColor = aFillColor | |
| 10 | aShape.strokeColor = aStrokeColor | |
| 11 | }; | |
| 12 | ||
| 13 | app.openURL( | |
| 14 | 'omnigraffle://localhost/omnijs-run?script=' + | |
| 15 | encodeURIComponent( | |
| 16 | '(' + OmniAutomationFunction + ')' + '()' | |
| 17 | ) | |
| 18 | ); | |
| 19 | })(); | |
Omni Automation Script with Text Input
IMPORTANT: Omni applications have an updated security architecture for the execution of external Omni Automation scripts via URLs, such as those generated and run by 3rd-party applications and webpages. This is detailed in the following documentation: omni-automation.com/script-url/
JavaScript action scripts can also provide the mechanism for extracting textual data from the host app and transfer it to Omni Automation scripts that can use that data within the targeted Omni applications.
| Template: Omni Automation Script with Text Input | ||
| 01 | (() => { | |
| 02 | function OmniAutomationFunction(inputFromDraftsApp){ | |
| 03 | // Omni Automation function statements go here | |
| 04 | }; | |
| 05 | ||
| 06 | // percent-encode passed content and function | |
| 07 | const docContent = draft.content; | |
| 08 | const contentString = JSON.stringify(docContent) | |
| 09 | const encodedContent = encodeURIComponent(contentString); | |
| 10 | const functionString = OmniAutomationFunction.toString(); | |
| 11 | const encodedFunction = encodeURIComponent(functionString); | |
| 12 | ||
| 13 | // construct and execute an “approvable” Omni Automation script URL | |
| 14 | app.openURL( | |
| 15 | 'lowerCaseOmniAppName://localhost/omnijs-run?script=' + | |
| 16 | '%28' + encodedFunction + '%29' + | |
| 17 | '%28' + 'argument' + '%29' + | |
| 18 | '&arg=' + encodedContent | |
| 19 | ); | |
| 20 | })(); | |
01-15 Wrapping the script action in a self-invoking anonymous arrow function (() => {//code})(); prevents conflicts between other script actions, run in sequence, that may use the same variables.
02-04 The Omni Automation script is placed within a function to enable it to be converted to text for inclusion later in an Omni Automation script URL.
03 Place the Omni Automation script code within the function
06 Extract text from the document and store it in a variable.
08-14 The host application uses the JavaScript method openURL() for opening the URL generated by within the arguments parens.
09 The Omni Automation script URL begins with the name of the targeted Omni application in lowercase characters, like: omnigraffle, or omnioutliner and is followed by the omnijs-run command with the script parameter. See this page for details about Omni Automation script links.
10-13 The standard JavaScript method encodeURIComponent() is used to percent encode the Omni Automation script, and the resulting string is then appended to the URL opening.
11-12 The function and optional arguments are placed with adjacent parens for execution (function)(arguments). In this example, the argument is the stored text.
| DO THIS ► | To use this template to create a new JavaScript script action in Drafts or 1Writer, copy the template into a new script, and then replace the placeholder at 03 with the Omni Automation script to run, and replace the placeholder at 09 with the lowercase name of the Omni Application to target. In addition, edit the text extraction line 06 to retrieve the desired text. |
Omni Automation Script with Paragraphs Array Input
Here’s a variation of the previous template, in which the text of the Drafts document is passed to the Omni Automation script as an array of paragraph strings:
| Template: Omni Automation Script with Paragraphs Array Input | ||
| 01 | (() => { | |
| 02 | function OmniAutomationFunction(arrayOfParagraphs){ | |
| 03 | // Omni Automation function statements go here | |
| 04 | }; | |
| 05 | ||
| 06 | // percent-encode passed content and function | |
| 07 | const textDataFromHostApp = editor.getText().split('\n'); | |
| 08 | const contentString = JSON.stringify(textDataFromHostApp) | |
| 09 | const encodedContent = encodeURIComponent(contentString); | |
| 10 | const functionString = OmniAutomationFunction.toString(); | |
| 11 | const encodedFunction = encodeURIComponent(functionString); | |
| 12 | ||
| 13 | // construct and execute an “approvable” Omni Automation script URL | |
| 14 | app.openURL( | |
| 15 | 'lowerCaseOmniAppName://localhost/omnijs-run?script=' + | |
| 16 | '%28' + encodedFunction + '%29' + | |
| 17 | '%28' + 'argument' + '%29' + | |
| 18 | '&arg=' + encodedContent | |
| 19 | ); | |
| 20 | })(); | |
01-15 Wrapping the script action in a self-invoking anonymous arrow function (() => {//code})(); prevents conflicts between other script actions, run in sequence, that may use the same variables.
02-04 The Omni Automation script is placed within a function to enable it to be converted to text for inclusion later in an Omni Automation script URL.
03 Place the Omni Automation script code within the function
06 Extract text from the document and store it in a variable.
08-14 The host application uses the JavaScript method openURL() for opening the URL generated by within the arguments parens.
09 The Omni Automation script URL begins with the name of the targeted Omni application in lowercase characters, like: omnigraffle, or omnioutliner and is followed by the omnijs-run command with the script parameter. See this page for details about Omni Automation script links.
10-13 The standard JavaScript method encodeURIComponent() is used to percent encode the Omni Automation script, and the resulting string is then appended to the URL opening.
11-12 The function and optional arguments are placed with adjacent parens for execution (function)(arguments). In this example, the argument is the stored text.
Here's an example that extracts the paragraphs of the current document and passes them to an Omni Automation script that appends each paragraph to the current OmniOutliner outline as rows.
| Append Paragraphs to Outline as Rows | ||
| 01 | (() => { | |
| 02 | // OmniOutliner JavaScript Context | |
| 03 | // Omni Automation script as a function with text input | |
| 04 | function appendItemsToOutline(stringsArray){ | |
| 05 | stringsArray.forEach(function(string){ | |
| 06 | rootItem.addChild(null, function(item){item.topic = string}) | |
| 07 | }) | |
| 08 | }; | |
| 09 | ||
| 10 | // Host Application JavaScript Context (1Writer, Drafts, etc.) | |
| 11 | const stringsArray = editor.getText().split('\n'); | |
| 12 | ||
| 13 | // percent-encode passed content and function | |
| 14 | const textDataFromHostApp = editor.getText().split('\n'); | |
| 15 | const contentString = JSON.stringify(textDataFromHostApp) | |
| 16 | const encodedContent = encodeURIComponent(contentString); | |
| 17 | const functionString = appendItemsToOutline.toString(); | |
| 18 | const encodedFunction = encodeURIComponent(functionString); | |
| 19 | ||
| 20 | // construct and execute an “approvable” Omni Automation script URL | |
| 21 | app.openURL( | |
| 22 | 'omnioutliner://localhost/omnijs-run?script=' + | |
| 23 | '%28' + encodedFunction + '%29' + | |
| 24 | '%28' + 'argument' + '%29' + | |
| 25 | '&arg=' + encodedContent | |
| 26 | ); | |
| 27 | })(); | |
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.
DISCLAIMER