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.

(() => { function OmniAutomationFunction(){ // Omni Automation script goes here }; app.openURL( 'lowercaseOmniAppName://localhost/omnijs-run?script=' + encodeURIComponent( '(' + OmniAutomationFunction + ')' + '()' ) ); })();

 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:

(() => { function OmniAutomationFunction(){ aRect = new Rect(100,100,200,200) aFillColor = Color.RGB(0, 0, 1, 1) aStrokeColor = Color.red cnvs = document.windows[0].selection.canvas aShape = cnvs.addShape('Circle',aRect) aShape.strokeThickness = 12 aShape.fillColor = aFillColor aShape.strokeColor = aStrokeColor }; app.openURL( 'omnigraffle://localhost/omnijs-run?script=' + encodeURIComponent( '(' + OmniAutomationFunction + ')' + '()' ) ); })();

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.

(() => { function OmniAutomationFunction(inputFromDraftsApp){ // Omni Automation function statements go here }; // percent-encode passed content and function const docContent = draft.content; const contentString = JSON.stringify(docContent) const encodedContent = encodeURIComponent(contentString); const functionString = OmniAutomationFunction.toString(); const encodedFunction = encodeURIComponent(functionString); // construct and execute an “approvable” Omni Automation script URL app.openURL( 'lowerCaseOmniAppName://localhost/omnijs-run?script=' + '%28' + encodedFunction + '%29' + '%28' + 'argument' + '%29' + '&arg=' + encodedContent ); })();

 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:

(() => { function OmniAutomationFunction(arrayOfParagraphs){ // Omni Automation function statements go here }; // percent-encode passed content and function const textDataFromHostApp = editor.getText().split('\n'); const contentString = JSON.stringify(textDataFromHostApp) const encodedContent = encodeURIComponent(contentString); const functionString = OmniAutomationFunction.toString(); const encodedFunction = encodeURIComponent(functionString); // construct and execute an “approvable” Omni Automation script URL app.openURL( 'lowerCaseOmniAppName://localhost/omnijs-run?script=' + '%28' + encodedFunction + '%29' + '%28' + 'argument' + '%29' + '&arg=' + encodedContent ); })();

 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.

(() => { // OmniOutliner JavaScript Context // Omni Automation script as a function with text input function appendItemsToOutline(stringsArray){ stringsArray.forEach(function(string){ rootItem.addChild(null, function(item){item.topic = string}) }) }; // Host Application JavaScript Context (1Writer, Drafts, etc.) const stringsArray = editor.getText().split('\n'); // percent-encode passed content and function const textDataFromHostApp = editor.getText().split('\n'); const contentString = JSON.stringify(textDataFromHostApp) const encodedContent = encodeURIComponent(contentString); const functionString = appendItemsToOutline.toString(); const encodedFunction = encodeURIComponent(functionString); // construct and execute an “approvable” Omni Automation script URL app.openURL( 'omnioutliner://localhost/omnijs-run?script=' + '%28' + encodedFunction + '%29' + '%28' + 'argument' + '%29' + '&arg=' + encodedContent ); })();
UNDER CONSTRUCTION

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

DISCLAIMER